---

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

date: 2020-11-07

layout: post

lang: en

ref: diy-an-offline-bug-tracker-with-text-files-git-and-email

---

When [push comes to shove][youtube-dl-takedown-notice], 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][sourcehut-ml]".

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][writethedocs-in-repo][^writethedocs-in-repo],
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.

[^writethedocs-in-repo]: Described as "the ultimate marriage of the two". Starts
    at time 31:50.

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 **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][todos-srht-email] or an API for
[bridging local bugs with vendor-specific services][git-bug-bridges]. 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.

[youtube-dl-takedown-notice]: https://github.com/github/dmca/blob/master/2020/10/2020-10-23-RIAA.md
[sourcehut-ml]: https://sourcehut.org/blog/2020-10-29-how-mailing-lists-prevent-censorship/
[writethedocs-in-repo]: https://podcast.writethedocs.org/2017/01/25/episode-3-trends/
[todos-srht-email]: https://man.sr.ht/todo.sr.ht/#email-access
[git-bug-bridges]: https://github.com/MichaelMure/git-bug#bridges

## 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.org`][todos-org] 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][org-mode-to-html], and
[publish][published-todos] 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][fossil-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.org` 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.

[todos-org]: https://git.euandreh.xyz/mediator/tree/TODOs.org?id=110c0af4ef53faf6e1ebe87905ce16766548607e
[org-mode-to-html]: https://git.euandreh.xyz/mediator/tree/scripts/build-site.sh?id=db4a727bc24b54b50158827b34502de21dbf8948#n14
[published-todos]: https://mediator.euandreh.xyz/tasks-and-bugs.html
[fossil-tickets]: https://fossil-scm.org/home/doc/trunk/www/bugtheory.wiki