1 files changed, 106 insertions, 0 deletions
diff --git a/_articles/2020-09-06-diy-an-offline-bug-tracker-with-text-files-git-and-email.md b/_articles/2020-09-06-diy-an-offline-bug-tracker-with-text-files-git-and-email.md
new file mode 100644
index 0000000..0eff520
--- /dev/null
+++ b/_articles/2020-09-06-diy-an-offline-bug-tracker-with-text-files-git-and-email.md
@@ -0,0 +1,106 @@
+---
+
+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
+
+published: false
+
+---
+
+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 alonside 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 may pick any name
+you like, or use a dedicated branch just for that, split tasks and bugs into
+different files, or have one file for each.
+
+These tools are familliar enough that you can adjust it to fit your workflow.
+
+[todos-org]: https://git.euandreh.xyz/mediator/tree/TODOs.org
+[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