Any software project with users other than the developers should make releases.

  • A release is the developers saying that the software is in a good shape and ready to be used. This is important for the users, since otherwise they would have to try various version control revisions to find something that looks like it might work. Linux distributions and others who package software want releases for the same reason.

  • Sysadmins want releases for an additional reason: they want to be able to reproduce an installation, so that they can have many identical machines.

  • Releases are important for the developers themselves as well. Without releases, it becomes harder to support users, since the first support step is to determine the version the user is running, and that becomes harder if it might be any commit from any branch in the history of the project.

Given that releases are useful, what's a good way to make them? A popular opinion today is that a release is made by tagging a commit in a version control repository. This is the minimum for what constitutes a release, and it's fine for many people. Your author is more picky.

For a proper release, the following is a reasonable checklist:

  • A tag in version control (in git, it should be OpenPGP signed).
  • A release tar archive, compressed using a suitable compression tool.
    • The archive may contain more files than are in the tagged version control commit. For example, autoconf-generated files for configuring a build.
  • A detached OpenPGP signature of the compressed tar archive.

An actual tar archive is necessary because it may not be possible to reproduce the release tar archive at a later date. For example, the way git produce a tar archive may change, and the compression tool may also change.

This even has security implications: it is plausible that an attack could happen by exploiting a flaw in the decompression software, if the attacker can use any compression program. If a release is made, and the release artifacts (tar archive, detached signature) are verified and tested, it gets much harder to construct an attack.


A short checklist for making a release:

  • Ensure the software is in a fit state to be released. It should work correctly; documentation, translations, and release notes should be up to date; and so on.
  • In particular, ensure the desired version number is correct and consistently applied across the software.
  • Sign the release tag.
  • Produce the release tar archive (compressed), including any generated files it should contain.
  • Produce the detached signature for the tar archive.
  • Produce any other release artifacts.
  • Test the release artifacts in some suitable way.
  • Publish the release artifacts and push the signed tag.
  • Announce the release in a suitable way: on the project website, blog, mailing list, or using a message in a bottle, depending on the project.
  • Figure out a way to automate as much as possible of this so it's easier to do the next time.

For most projects, making a release should happen often enough that it pays off to automate most of the process.