Best practice in release management for open source projects

by Sander van der Waal on 26 October 2010 , last updated

Introduction

Release management is about managing the process of building, packaging and distributing software for consumption. In release management in open source projects we explain the process of release management in open source software projects. In this document we will focus on some of the best practices in release management and will supply a checklist to help you define and streamline your project’s release management process.

Release early, release often

Even if you have no users outside the core project team, creating a release at an early stage of the project will ensure that, at a time when it is easy to do so, you build the tools and infrastructure for doing quick releases. If you leave this until later, the codebase will have grown in size and complexity. This makes it harder to set up the build process.

In addition, while the source code is freely available and developed in an open manner, potential developers and users will generally want to be able to evaluate it quickly and easily. You should therefore release your project’s software frequently, and in a form that is easily accessible and can be used by developers in any environment. By doing so, you will make it easier for people to contribute. If you tackle it early enough, you will find the creation of a semi-automated build-and-release system reasonably simple.

Release early, release often is a well-known mantra in open source development. Some of the more compelling reasons for this are that it:

  • encourages early and frequent feedback
  • provides easy access to the latest and greatest features
  • builds developer confidence
  • shows genuine project activity
  • facilitates a manageable upgrade path for users

Many projects resist releasing early, saying that the code is unfinished, that it needs to be polished a little or that it has not been fully tested yet. It is often quite scary releasing software that is not considered ready. However, the truth is that applications are rarely finished, the code can always be polished and the best way to test is to put it in the hands of early adopters.

Release early, release often is an important part of building a sustainable open source project. Releases result in users, users sometimes become contributors, and contributors make the project stronger. The downside of releasing early and often, however, is that you need to manage your user expectations. Be clear about the true status of your release and draw users’ attention to any known bugs in your documentation.

Many projects release in stealth mode until they are reasonably feature complete. That is, they do not seek to advertise their existence and do not provide user-focussed websites, thus naturally filtering for early adopters. Releasing your project in stealth mode will allow those really interested in your work to find you and get started easily. On the other hand, you are less likely to attract end users who are not interested in projects that are at an early stage of development.

It is common practice to move to time-based releases as soon as possible. Creating a predictable release cycle (such as releasing once every 6 months) benefits the community by providing deadlines for contributors, and allowing users to plan for upgrades.

Provide appropriate documentation

Users expect to find a minimal set of documentation in the root directory of a release. In this section we describe those documents, listed by the filenames they usually appear under. Make sure that all documentation is proofread and, in the case of things like installation instructions, tested as well.

README.txt

The README.txt is where the users will go first, once they have downloaded your distribution. This should give the bare minimum of information on the release and how to start working with it. At the very least, it should include instructions on how to get started and details of where to find more information.

RELEASE-NOTES and CHANGES

These files are a reference for users recieving the new release to find out what has changed from the previous version. While it’s not strictly defined which information should be in which file, you should ensure you conform the the practices of similar projects, such as those managed by the same foundation as your own.

The release notes should contain a description of the project and an overview of what this new release provides. They should not provide detailed change information, but should list the headline changes that will encourage users to upgrade. These could include new features and major bugfixes in the new release, as well as detailing any known issues with the release.

This document should also contain information on where to get the various distributions and where to find more information, as it will often be used when announcing a release to the outside world. That is, it should be a meaningful document even when not located in a distribution.

The CHANGES file is a document describing the bug fixes, new features and API changes found in this release. Logs from the version control system can be used to collect changes, but this can result in too detailed a view of things. For example, a spelling correction in the documents does not warrant an entry in the changes document. This is a good opportunity to reinforce the need for good commit messages: each commit should contain work for only one issue or feature, and messages should be clear and concise.

Some tools provide a means for managing change documents independently of the version control system. This allows much more control over what appears in your changes document and so makes the document more useful to users. For users who are interested in more detail, you could also include information of where to find your project’s version control logs.

LICENCE and NOTICE

A file named LICENCE in the root directory should clearly indicate the licence in use. You may also require a NOTICE text, but this will depend on the licences of the libraries you include in your distribution. Some licences require that you credit the authors of any code that you have included under that licence. This is as simple as copying the contents of the NOTICE files from each upstream project you use, and including it in your own.

Sign your releases

Releasing executables through your own (or a hosting) website is not entirely risk-free. If someone tampers with your binaries, for example by adding malware to the code, your users may be downloading malicious code to their computers by using your software. Of course you would want to prevent that. We will focus on two ways of doing this: adding a checksum to the download and making this available as a separate file, and signing the release with a PGP signature.

Adding a checksum to your download

Several algorithms have been developed to generate a hash checksum for a file, for example MD5 or the SHA family (SHA1, SHA128, SHA512). The purpose of creating this message digest is to ensure that the file you downloaded is exactly the same file that was offered, so not one byte can be different. This will help you to not only prevent infringement from outsiders, but also detect technical errors in the transmission of the file.

Some code hosting websites assist with this by generating a checksum for you and making this automatically available for users who download your software. For example, Google Code does this. They provide SHA1 hashes for all downloads that you make available through the download section of a Google Code hosted project.

An easy, simple-to-use tool to generate hashes yourself is the open source application GNU Privacy Guard (GPG). It supports MD5 as well as several SHA algorithms. The process is fairly simple. You create the checksum file for the generated download and upload them both to your website. The user interested in the download also downloads the checksum and uses a tool similar to GPG to check if the checksum is correct. In general, when generating a hash key, you should use the algorithms with the longest hash key, as they are more secure. With brute force it is possible to break all hash keys, but a short key like MD5 is much easier to crack than one like SHA512.

Signing your release with a PGP signature

Another way to protect your released binaries is to sign them with a PGP signature. You can use the same tool (GPG) for that. When you start using it, you first need to generate a public/private key combination. You will then have to publish the public key in a file. Commonly, there is one KEYS file for the whole project that contains the public keys of all relevant developers. Next, you can sign a release binary using your own key, which will result in a signature file. A signature file is quite similar to a hash key file.

Now anybody who can download the binary, your public key and the signature file, can also check whether the signature matches the public key and the binary. This will ensure that the file that has been downloaded is the same file that has been created by you, the release manager. PGP signatures can provide an extra level of protection by identifying that the public/private key combination that signed the binary is indeed linked to the individual. It works in a decentralised way (as opposed to the PKI method, which needs a certifying authority). Once you have created your own keys, you can exchange your public key with other users and thereby add them to your web of trust. You do that by signing each other’s keys. You should really do this in person, perhaps at a conference, to make sure that you know who you are dealing with.

Checklist

The checklist below will help you to ensure that everything you need to do in a release has been done. Individual projects will need to add some other checks, but this is a good starting point.

Distributions

Compressed distributions unpack correctly

Documentation is readable

Licences for libraries are distributed together with any applicable NOTICEs

Licences comply with project policy

LICENCE and NOTICE documents contain required sections

All text files contain correct licence header

Files with licences other than the main project licence are mentioned in LICENCE

All file headers comply with project policy

Distributed artefacts

A meaningful readme.txt document is present in all distributions

LICENCE and NOTICE files are present in all distributions

Source distribution

A meaningful readme.txt document is present

Build instructions exist and the source builds using these instructions

Licence headers are correctly applied

There are no version control files in the distribution

The source is exported from a tag from the version control system

OpenPGP keys

KEYS file contains signing key

The key has been uploaded to regular public key servers

Further reading

Links:

Related information from OSS Watch