How to make your downstream users happy February 9, 2021 on Drew DeVault's blog

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, 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 for your releases — consider putting a changelog into your annotated tags (git tag -a). If you have good commit discipline in your project, then you can easily use git shortlog to generate such a changelog from your commit messages. This helps us understand what we can expect when upgrading, which helps incentivize us to upgrade in the first place. In How to fuck up software releases, I wrote about my semver 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.

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!

Have a comment on one of my posts? Start a discussion in my public inbox by sending an email to ~sircmpwn/public-inbox@lists.sr.ht [mailing list etiquette]

Articles from blogs I read Generated by openring

Status update, July 2021

Hi! This status update comes a bit late, because I was on leave, biking in the south of France for a few days. This month I’ve released mako 1.6, to try to make up for the long delay for the last release. mako 1.6 brings quality-of-life improvements: modes a…

via emersion July 21, 2021

The mythical 10× programmer is just a good leader

There is some truth to the idea that some programmers are more productive than others. In practice, this is mainly a function of the breadth and depth of their experience, rather than an expression of innate talent. Under the right circumstances, the differe…

via Blogs on Sourcehut July 17, 2021

Summary of changes for June

Hey everyone! This is the list of all the changes we've done to our projects and apps during the month of June. We'll also be reporting in our on position in the world, and on our future plans. Summary Of Changes Nasu, released a nasu guide, and…

via Hundred Rabbits July 1, 2021