DIY an offline bug tracker with text files, Git and email

When push comes to shove, the operational aspects of governance of a software project matter a lot. And everybody likes to chime in with their alternative of how to avoid single points of failure in project governance, just like I’m doing right now.

The most valuable assets of a project are:

1. source code
2. discussions
3. documentation
4. builds
5. tasks and bugs

For source code, Git and other DVCS solve that already: everybody gets a full copy of the entire source code.

If your code forge is compromised, moving it to a new one takes a couple of minutes, if there isn’t a secondary remote serving as mirror already. In this case, no action is required.

If you’re having your discussions by email, “taking this archive somewhere else and carrying on is effortless”.

Besides, make sure to backup archives of past discussions so that the history is also preserved when this migration happens.

The documentation should live inside the repository itself¹, so that not only it gets first class treatment, but also gets distributed to everybody too. Migrating the code to a new forge already migrates the documentation with it.

As long as you keep the builds vendor neutral, the migration should only involve adapting how you call your tests.sh from the format of provider-1.yml uses to the format that provider-2.yml accepts. It isn’t valuable to carry the build history with the project, as this data quickly decays in value as weeks and months go by, but for simple text logs using Git notes may be just enough, and they would be replicated with the rest of the repository.

But for tasks and bugs many rely on a vendor-specific service, where you register and manage those issues via a web browser. Some provide an interface for interacting via email or an API for bridging local bugs with vendor-specific services. But they’re all layers around the service, that disguises it as being a central point of failure, which when compromised would lead to data loss. When push comes to shove, you’d loose data.

Alternative: text files, Git and email

Why not do the same as documentation, and move tasks and bugs into the repository itself?

It requires no extra tool to be installed, and fits right in the already existing workflow for source code and documentation.

I like to keep a TODOs.md file at the repository top-level, with two relevant sections: “tasks” and “bugs”. Then when building the documentation I’ll just generate an HTML file from it, and publish it alongside the static website. All that is done on the main branch.

Any issues discussions are done in the mailing list, and a reference to a discussion could be added to the ticket itself later on. External contributors can file tickets by sending a patch.

The good thing about this solution is that it works for 99% of projects out there.

For the other 1%, having Fossil’s “tickets” could be an alternative, but you may not want to migrate your project to Fossil to get those niceties.

Even though I keep a TODOs.md file on the main branch, you can have a tasks branch with a task-n.md file for each task, or any other way you like.

These tools are familiar enough that you can adjust it to fit your workflow.