commit: c9157011907a37f4e0fe743edf47761191b3d60e
parent 289724177cb8f17a14bfbf7fd19e3f0fa0d37353
Author: Drew DeVault <sir@cmpwn.com>
Date: Tue, 9 Feb 2021 08:50:32 -0500
Downstreams
Diffstat:
2 files changed, 66 insertions(+), 2 deletions(-)
diff --git a/content/blog/How-to-make-your-downstreams-happy.md b/content/blog/How-to-make-your-downstreams-happy.md
@@ -0,0 +1,63 @@
+---
+title: How to make your downstream users happy
+date: 2021-02-09
+---
+
+There are a number of things that your FOSS project can be doing which will make
+the lives of your downstream users easier, particularly if you're writing a
+library or programmer-facing tooling. Many of your downstreams (Linux distros,
+pkgsrc, corporate users, etc) are dealing with lots of packages, and some minor
+tweaks to your workflow will help them out a lot.
+
+The first thing to do is *avoid* using any build system or packaging system
+which is not the norm for your language. Also avoid incorporating information
+into your build which relies on being in your git repo — most packagers
+prefer to work with tarball snapshots, or to fetch your package from e.g. PyPI.
+These two issues are definitely the worst offenders. If you do have to use a
+custom build system, take your time to document it thoroughly, so that users who
+run into problems are well-equipped to address them. The typical build system or
+packaging process in use for your language already addressed most of those edge
+cases long ago, which is why we like it better. If you must fetch, say, version
+information from git, then please add a fallback, such as an environment
+variable.
+
+Speaking of environment variables, another good one to support is
+[SOURCE_DATE_EPOCH](https://reproducible-builds.org/docs/source-date-epoch/),
+for anything where the current date or time is incorporated into your build
+output. Many distros are striving for *reproducible* builds these days, which
+involves being able to run a build twice, or by two independent parties, and
+arrive at an identical checksum-verifiable result. You can probably imagine some
+other ways to prevent issues here — don't incorporate the full path to
+each file in your logs, for instance. There are more recommendations on the
+website linked earlier.
+
+Though we don't like to rely on it as part of the formal packaging process, a
+good git discipline will also help us with the informal parts. You may already
+be using [git tags][0] for your releases — consider putting a changelog
+into your annotated tags (git tag -a). If you have [good commit discipline][1]
+in your project, then you can easily use [git shortlog][2] to generate such a
+changelog from your commit messages. This helps us understand what we can expect
+when upgrading, which helps incentive us to upgrade in the first place. In [How
+to fuck up software releases][3], I wrote about my [semver][4] tool, which you
+may find helpful in automating this process. It can also help you avoid
+forgetting to do things like update the version number somewhere in the code.
+
+[0]: https://git-scm.com/docs/git-tag
+[1]: https://drewdevault.com/2019/02/25/Using-git-with-discipline.html
+[2]: https://git-scm.com/docs/git-shortlog
+[3]: https://drewdevault.com/2019/10/12/how-to-fuck-up-releases.html
+[4]: https://git.sr.ht/~sircmpwn/dotfiles/tree/master/bin/semver
+
+<iframe src="https://asciinema.org/a/nzBvuMXjUMsoewLnrbTm7E28O/embed?" id="asciicast-iframe-nzBvuMXjUMsoewLnrbTm7E28O" name="asciicast-iframe-nzBvuMXjUMsoewLnrbTm7E28O" scrolling="no" allowfullscreen="true" style="overflow: hidden; border: 0px; width: 540px; float: none; visibility: visible; height: 404px;"></iframe>
+
+In short, to make your downstreams happy:
+
+1. Don't rock the boat on builds and packaging.
+2. Don't expect your code to always be in a git repo.
+3. Consider reproducible builds.
+4. Stick a detailed changelog in your annotated tag — which is easy if you
+ have good commit discipline.
+
+Overall, this is pretty easy stuff, and good practices which pay off in other
+respects as well. Here's a big "thanks" in advance from your future downstreams
+for your efforts in this regard!
diff --git a/content/blog/Using-git-with-discipline.md b/content/blog/Using-git-with-discipline.md
@@ -72,10 +72,11 @@ because if you can expect the code to compile and complete tests successfully
for every commit, you can pass `git-bisect` a script which programmatically
tests a tree for the presence of a bug and avoid false positives. These
self-contained commits with good commit messages can also make it really easy to
-prepare release notes with [git-shortlog][shortlog], [like
-Linus does with Linux releases][linux-announcement].
+prepare release notes with [git-shortlog][shortlog],
+[like Linus does with Linux releases][linux-announcement].
[^2]: In a nutshell, git bisect is a tool which does a binary search between two commits in your history, checking out the commits in between one at a time to allow you to test for the presence of a bug. In this manner you can narrow down the commit which introduced a problem.
+
[shortlog]: https://git-scm.com/docs/git-shortlog
[linux-announcement]: https://lkml.org/lkml/2019/1/6/178
