From 570ec471d1605318aeefb030cd78682ae442235b Mon Sep 17 00:00:00 2001 From: EuAndreh Date: Mon, 31 Mar 2025 21:51:40 -0300 Subject: src/content/: Update all files left to asciidoc --- src/content/blog/2020/11/07/diy-bugs.adoc | 122 +++++++++++++----------------- 1 file changed, 53 insertions(+), 69 deletions(-) (limited to 'src/content/blog/2020/11/07/diy-bugs.adoc') diff --git a/src/content/blog/2020/11/07/diy-bugs.adoc b/src/content/blog/2020/11/07/diy-bugs.adoc index b1dd117..0f561c1 100644 --- a/src/content/blog/2020/11/07/diy-bugs.adoc +++ b/src/content/blog/2020/11/07/diy-bugs.adoc @@ -1,79 +1,67 @@ ---- - -title: DIY an offline bug tracker with text files, Git and email - -date: 2020-11-07 - -updated_at: 2021-08-14 - -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 += DIY an offline bug tracker with text files, Git and email + +: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:../../../../tils/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: -1. source code -2. discussions -3. documentation -4. builds -5. tasks and bugs +. 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. +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 +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]". +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 -[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 +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. -[^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 +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. - -[using Git notes]: {% link _tils/2020-11-30-storing-ci-data-on-git-notes.md %} - -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 +`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. +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 -## 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? @@ -81,28 +69,24 @@ 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. +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 +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 +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. +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.md`]: https://euandre.org/git/remembering/tree/TODOs.md?id=3f727802cb73ab7aa139ca52e729fd106ea916d0 -[generate an HTML file from it]: https://euandre.org/git/remembering/tree/aux/workflow/TODOs.sh?id=3f727802cb73ab7aa139ca52e729fd106ea916d0 -[publish]: https://euandreh.xyz/remembering/TODOs.html -[fossil-tickets]: https://fossil-scm.org/home/doc/trunk/www/bugtheory.wiki -- cgit v1.2.3