= DIY an offline bug tracker with text files, Git and email
:updatedat: 2021-08-14

:attack-on-ytdl: https://github.com/github/dmca/blob/master/2020/10/2020-10-23-RIAA.md
:list-discussions: https://sourcehut.org/blog/2020-10-29-how-mailing-lists-prevent-censorship/
:docs-in-repo: https://podcast.writethedocs.org/2017/01/25/episode-3-trends/
:ci-in-notes: link:../../../../til/2020/11/30/git-notes-ci.html
:todos-mui: https://man.sr.ht/todo.sr.ht/#email-access
:git-bug-bridges: https://github.com/MichaelMure/git-bug#bridges

When {attack-on-ytdl}[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:

. source code
. discussions
. documentation
. builds
. 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, "{list-discussions}[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 {docs-in-repo}[live inside the repository
itself]footnote:writethedocs-in-repo[
  Described as "the ultimate marriage of the two".  Starts at time 31:50.
], 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
{ci-in-notes}[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
{todos-mui}[interface for interacting via email] or an API for
{git-bug-bridges[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

:todos-example: https://euandre.org/git/remembering/tree/TODOs.md?id=3f727802cb73ab7aa139ca52e729fd106ea916d0
:todos-script: https://euandre.org/git/remembering/tree/aux/workflow/TODOs.sh?id=3f727802cb73ab7aa139ca52e729fd106ea916d0
:todos-html: https://euandreh.xyz/remembering/TODOs.html
:fossil-tickets: https://fossil-scm.org/home/doc/trunk/www/bugtheory.wiki

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-example}[`TODOs.md`] file at the repository top-level,
with two relevant sections: "tasks" and "bugs".  Then when building the
documentation I'll just {todos-script}[generate an HTML file from it], and
{todos-html}[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 "{fossil-tickets}[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.
