Boiling Steam: Powered By Gitea… and Much More!

How does Boiling Steam work behind the scenes? What’s Gitea? There is not much point in talking about the CMS (Content Management System) we use (WordPress), because that would be a rather boring topic in itself… Rather, how does the small team behind our publication actually organize itself? And what tools do we use and how does Gitea fit into it?

The Key Setup: Offline First

Boiling Steam is a team of 4 contributors currently (Patola, Podiki, Cow_Killer and myself, Eki), and we so happen to be working in very different locations and time zones (from the US to Japan – making our time online together rather limited). So everything we do has to assume other members are potentially offline or not available – so we adopt an ASYNC mindset: we work in parallel as much as possible and reduce sequential operations to the minimum.

Of course, we still have some time online every single day, and we need a communication tool to chat and interact. We do have each other’s emails but we rarely use it for communication. Instead… we use Matrix.

Communication: Matrix/Element

The amount of tools for chatting online is staggering these days. Great amount of choice, even if you only want to use FOSS tools. In our case we have settled on Matrix (and Element as a client, but there are many others) for the following:

  • FOSS solution
  • Could be completely decentralized if we ever wish to (self hosting) – for example Podiki joins us on Matrix from his own self-hosted Matrix server, and you can see that from his username being on his domain. He mentioned that in an article he wrote for Vice not too long ago.
  • End to End encryption
  • Works well on Desktop and Mobile (iOS and Android)
  • Makes it possible to do audio/video calls too. (powered by the Jitsi integration)

Also, we are generally quite happy with how it works: not too many issues (videoconferending is not perfect though) and this is really helpful to leave some messages when some of us go to bed while the others still have a good half day ahead of them.

That’s fine for casual chat and info sharing, but when it comes to coordinating articles, we have settled on a git repository, and the web app Gitea to manage it, as our main system. We also self-host Gitea (it’s very simple to deploy!) on one of our servers for additional flexibility. As you see we don’t just talk about FOSS, we also actively make use of it 🙂

Gitea on the web, hosted on Github

Podiki has also a separate self-hosted Gitea instance where he mirrors our main server’s git, as a backup in case things go wrong. We have been working with this for a fairly long time now, and this system has proven very robust.

Enter Gitea: Git Repository, Issue Tracking and Overall Management

Gitea is, to put it simply, an app made to access, modify and manage a git repository through a web interface. You should be using it mostly for code versionning, but it also works for managing a publication. Let us see in more details how we use it:

Everything is done in Markdown

To leverage a code versioning tool which relies on text and lines like Git, we adopted a standard across all of draft articles: they need to written in Markdown (if you are not familiar with Markdown, it’s a very simple markup format which uses visual cues to mark text up). Markdown is largely sufficient for blogging and there is virtually no need to go beyond that. The other advantage is that everyone can use their preferred text editor as well. I do everything in Vim (with the Goyo plugin) for example, while Podiki likes to do everything in Emacs (his documents are actually .org files, but they render just fine as well on Gitea’s web interface, it’s in any case still text). Cow_killer likes to use the text editor included in the Gitea interface: at the end of the day it does not matter as format is always, always text.

Every change can easily be tracked

Because we use git as a central system, all changes to every article are clearly tracked to whoever did them and what they modified. Since git manages changes at the ‘line’ level, a long paragraph in text is usually considered as a single line. So changing a typo somewhere in the paragraph would show that the whole paragraph has been replaced instead of just the typo itself. This is were git is not ideal for text editing as code and text follow different conventions (code lines tend to be short). But it’s not as bad as you might think. When you have a very long article anyway, just looking at the history tab and focusing on the few paragraphs that changed is still a very effective way to review the improvements.

Gitea: tracking the modification done on one article

You can see that Gitea’s web interface for history will highlight within the changed paragraph has been added with a different shade of green. Very practical.

Every new article is a branch

If you are familiar with git, you know that there is a master branch which keeps the current version of the repository, and collaborators typically use branches to implement new features or bug fixes. We do the same thing, except that we work with articles. Branches make it possible for us to make a clean separation between what’s ready to be published and what still needs work, reviewing or polishing.

Once we are all happy with how an article shaped up, we then merge it into the master branch.

Every new article is an issue

At the same time as we create a new branch for articles, we typically create a new issue in Gitea too. Issues are usually there for bug reports or bug tracking purposes. We use them to track what articles are currently in progress. Issues have their own discussion threads, so it’s very practical for us to exchange thoughts, ideas, and feedback on what we write about. This also touches on something very fundamental to how we work: Peer Review.

Peer Review Process

Boiling Steam typically focuses on longer features, reviews, guides, less so on news. We do cover some news that we consider very relevant, but most of the time if you want news you should subscribe to our Mastodon or Twitter feeds instead – this is where we share them. On the site, we all enjoy doing these bigger pieces and spending time getting it as good as we can.

The Peer Review process helps avoiding numerous pitfalls related to every topic we write about, and is also a way to validate that each article is at least insightful to read. You can ask all of us and I think we all agree that all of our articles benefit a lot from the additional points of view: I can’t think of a case where it did not help or did not bring any improvement.

Gitea: a short extract on the issue system that we use for Peer Review to ensure our articles are as robust as possible

To give you a couple of examples:

  • For the recent Max Payne 3 article, I had completely skipped a proper introduction to the series, assuming that most people would be familiar with Max Payne already. Turns out that this is far from being the case, and new generations of gamers are much less likely to have heard about it. So I added a lot of background details and explained the mechanics of the series in more depth.
  • For Podiki‘s Move to AMD article the initial draft sparked a lot of questions from us Nvidia users, and resulted in more testing, more confirmations, and more details on how to do the actual transition on an established system.

Doing Peer Review also works well because we all have different backgrounds, tastes and experiences. If we were all from the same mold, it would not be nearly as helpful, nor let us reach beyond an audience we know individually.

Peer Review should not be considered a silver bullet. It will not magically make all errors disappear or render every article perfect. But the more we have feedback, the more we can fix our individual blind spots, so the articles you end up reading are much more robust than their very first draft.

There is no set period for Peer Review: it can take a few days to a few weeks, in case the article demands it. I would say that on average it takes 4-5 days between several rows of feedbacks and a final version. It’s definitely taking more time to follow such a process rather than just writing and pushing articles as soon as we have a draft ready.

How do we deal with the fact that articles may take longer to finalize because of them? Well, we ensure we have a constant stream of new potential articles that we are working on: as long as we work on parallel on several of them, we will be able to release a few articles every week, statistically.

Issues live on the Kanban

We used the track the status of all articles on a Markdown file, between Ideas, Drafts in Progress, Drafts Under Review, and Articles To be Published categories. It was OK, but last year Gitea has finally introduced a Kanban view to manage issues visually just like you could do it on Trello, for example, or many other systems focused on Agile development.

Gitea: the kanban view we use to track our progress on multiple articles at the same time

This has made it easier to link our Issue threads to an overall status, and we can therefore have better control as to what we plan to publish on a weekly basis.

Alerts

While most of the process relies on manual tasks, we have a few automated alerts to make sure we do not waste time either. Not everyone is logged in the Gitea at all times (we all have our other occupations after all), but we do have an alert system that sends an email every single time a change occurs on the git repository. If I was waiting for Cow_killer to update his article, as soon as I get the email notification I can go back to Gitea and check what’s happening. In practice, I’m not that fast, but at least I know it’s pending.

An email alert sent by Jenkins, constantly watching for changes on the Gitea repository

How do such alerts work? Well, we also have a Jenkins instance. Jenkins is a Python piece of software that is usually used for CI/CD – it’s made to interface well with code repositories, so I use it to watch the repository using webhooks, and when changes happen it triggers a Jenkins workflow that will pull some relevant info and send it to everyone by email. Nothing too fancy, but very practical at the end of the day.

Transparency

One of the other aspects of doing everything through a git repository is that everything is completely transparent. Everyone can see the whole discussion, the edits, and comment on what is happening. There is no hidden authority, no secret trade-offs: the whole history is open to everyone in the Boiling Steam editorial team, and changes are justified by a clear reason.

To me the transparency aspect is almost as important as the operational process: I would not have it any other way.


Support our work on Patreon (or Liberapay) because it helps us cover more news and produce more articles related to the Linux gaming world!


The future

We are always thinking on how we can improve our ways of working:

  • Any new tool we can use?
  • A way to better communicate?
  • Some more things we could self-host that make sense?

We don’t necessarily make changes on a weekly basis, but come back in one year and there’s certainly some aspects that will have evolved and improved. As as our team keeps growing, we will face new needs and we will certainly have to review again how to best achieve our goals, to serve the Linux gaming community.


BoilingSteam lets you access our content for free, but writing articles is a constant investment. We don't use ads or sponsporship, help us make our activities sustainable by donating via Patreon or LiberaPay if you prefer it anonymous. You can follow what we do via our newsletter, our RSS feed, our Mastodon profile or our Twitter feed. We also have Peertube, Youtube and LBRY channels. If you'd like to chat, you can also find us on #boilingsteam:matrix.org. (what is Matrix?)

5 2 votes
Article Rating
Subscribe
Notify of
guest
9 Comments
Newest
Oldest Most Voted
Inline Feedbacks
View all comments
Guy Tea

Good lineup, same as mine for Gitea/Matrix. I prefer to use synapse for Matrix because one of my little prides is that my entire little network of servers runs on a Raspberry Pi over Docker, and I’d rather have a Go Matrix server than a Python one for perf. Also two things that are cool/would be interesting to add in a pure self-hosted and DIY spirit: Nextcloud, kind of overkill but the ability to just upload any file without any constraints to a group and letting them access it immediately is just priceless, it’s a “your own cloud” even if… Read more »

Erich Hoover

Markdown only creates new paragraphs when you have two returns, so if you want to have more granularity in your diff then you can start a new line after each sentence.

Screenshot from 2021-09-20 10-50-17.png
Steven McCurdy

Nice setup, have you thought about integrating a static site generator and ditching WordPress? Building It could be added to Jenkins very easily.

Grigi

This is very cool. Using software collaboration strategies for anything text based is always very useful.

Do you have some kind of article staging system so you can see how it actually looks without having to run it on a local server?
I’m just thinking of ways to make reviews of, e.g. lots of images?

Or is the built-in Markdown preview good enough?

Grigi

That’s great 🙂
Sounds like you have a slick & FOSS collaboration system 🙂