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.
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:
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.
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.
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.
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.
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. This document is usually the first port of call for users upgrading from a previous version.
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.
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. For example, it is common practice for projects at the Apache Software Foundation to include all third-party notices in the NOTICE file.
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.
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. Google Code is an example of 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 (PG). 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 PG 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.
Another way to protect your released binaries is to sign them with a PGP signature. You can use the same tool (GNU Privacy Guard) 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.
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.
It is licensed under the
Creative Commons Attribution-ShareAlike 2.0 England & Wales licence.
OSS Watch is funded by the Joint Information Systems Committee.
