Release management in open source software 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 this document we will explain the process of release management in open source software projects and highlight the most important steps in this process. We have also published a document that elaborates on the technical details of best practice in release management and provides a checklist that can be useful when making a release.

Introduction

In open source software projects, it is important that the software is released early and often. It is essential to have a well-defined process in place for creating these releases - much more important, in fact, than it is for most other activities in software development. This is necessary to ensure that all legal issues are addressed and that the quality of a release is good enough to be useful to users. This does not mean that a release must be complete or that it must be bug-free; in practice, this is never really the case. It simply means that the status of each release is well documented, in order to manage user expectations.

You will see that the tools that are important in an open source software project also play an indispensable role in release management. The most important tools in this respect are:

  • Mailing lists for communication
  • The issue tracker for release-planning and scope management
  • The version control system for tracking and tracing the released code

There are a number of roles in the release management process. In an early-stage project, it is likely that these roles will be carried out by a single person. As a project matures, they can be separated out and delegated to different team members. The different roles in the release management process are:

  • Architect: the person responsible for identifying, creating and implementing the release process
  • Manager: the person overseeing the release process
  • Facilitator: the liaison between all stakeholders in a release

Let’s take a look at the most important steps in the release management process.

Scope and planning

There are a couple of issues that are generally important for open source projects, but become crucial when the project considers creating a release. First of all, it is essential to ensure licence compatibility of the code. It is likely that the project’s code depends on some external libraries, each of which will have its own software licence. The architect will have to check whether the licence of that library permits the project to redistribute it with its own code. Ideally, this will happen the first moment this library is used in the project, but in any case should be no later than when the first release is prepared. Also, it is important for the project to make sure that all issues regarding intellectual property (IP) have been taken care of. Just as with licence compatibility, this should be done on an ongoing basis, but is especially important when preparing a release of the code.

When preparing a new release, the release manager needs to determine its scope and planning. They should involve the committers and users and seek some level of agreement from them about the scope and planning of the release. This is because the users will play a very important role in testing the prospective release and adopting the release once it has been made final. For this reason, all communication about the scope and planning of the release should be publicly accessible, for example via a public mailing list. While this process is usually overseen by the release manager, it may be controlled by the facilitator.

Central to the release-planning process is the issue tracker. This tool is used to document the status of all issues relating to the project and provides a means of scheduling and keeping track of which issues will be in which release. How the scope and planning of the release is achieved depends largely on how the project is governed. From a technical perspective, it will usually be the architect who will need to analyse the list of unresolved issues prior to release. In collaboration with the release manager, they will decide which issues will be resolved in this release and which will be moved to a later release. They should not attempt to fix all issues in any given release as this is a sure way of ensuring that the release never happens. Any issues that are to be delayed should be moved to a later release in the issue tracker so that a known issues list and a roadmap for the release can be created. If the issue had previously been scheduled for a release but after consideration is being delayed, this should be recorded in the release documentation so that users will know that this part of the schedule has not been met.

Slippage of an individual issue is not always a bad thing, so it is generally not a problem if issues are moved to a later release. It will serve as a reminder to the project’s users about what they can expect in the next release. If the release manager clearly indicates that the active developers will not address a given issue in a given release, users can decide just how important it is to them. If it is important enough, they can contribute to the project themselves by providing a patch. This is just one example of why communication is essential for keeping everybody informed throughout the process.

Version numbering

Each release will have to be uniquely identifiable by a version number. These numbers are not fully arbitrarily but are used according to a specific scheme that will give you additional information about the release. There are various schemes for expressing version numbers in software releases. We will briefly discuss one of the more common schemes, whereby version numbers are of the form x.y.z or <major>.<minor>.<micro>. The major version number is increased only when a significant amount of new functionality is added to the previous release. In such cases, the new release version number will be (x+1).0.0. The minor version number is increased only when some functionality is added to the new release, in which case the new release version number will be x.(y+1).0. When the new release consists mainly of bug fixes, there will be a so-called point release. The version number of the new release in such cases will only have the the micro version number increased, resulting in x.y.(z+1).

Some projects, however, use postfixes in the version number to indicate the stability of the code. For example, -alpha indicates unstable code, while -beta indicates code with a stable API (Application Programming Interface) but that may still have bugs in it. Other projects use the minor version number to indicate stable/unstable code, with an even number for stable releases and an odd number for unstable releases. In this context, unstable does not mean it is unusable. It simply means that the code may change in the next release. It serves as a warning to potential users that they should only use these releases if they are prepared to put the effort into maintaining their software when it comes to upgrading. This may require some extra manual steps in the upgrade.

Release candidates

It is good practice to create a release candidate (RC) before publishing a final release. An RC is a normal release, except that the version number has a postfix -RCx (x starting at 1 and increasing with every new release candidate) to indicate that it is not the final release. This means that it has not yet been approved and may contain critical bugs. The reason for creating an RC is to include a test cycle in the release process. Every release should be tested on as many platforms and by as many users as possible, and the best way to do that is by distributing an RC. An RC differs from a final release in the version number postfix only; other than that, it is a regular release.

The release candidate will be created using the version control system. Release management is one of the many important reasons why using a version control system is so crucial to a software project. It allows the project to develop further on the main branch, or trunk, of the project, while work continues on the release in a separate release branch without interfering with the main development activities. Even when the project team doesn’t want to create a release branch, they should still generate a tag so they can always go back and recreate the release from the same source code.

It is useful to adopt a reasonable naming convention when creating a release branch or a tag. This allows release tags to be recognised easily. Typically, the tag will be a variation on the name of the release. For example, some projects use ALL CAPS to indicate release tags. Thus, foo-1.2 would be tagged FOO-1-2. It is generally better to use ‘-‘ rather than ‘_’ as in most browsers the ‘_’ gets lost when a hyperlink is underlined.

Communication with the community is very important at every stage of the release process, but especially so in the period just before the architect creates the release branch. Because of the distributed nature of open source projects, communication is essential for making sure that all developers will have committed the code that is part of the agreed scope of the project, in time. After all code has been committed, the architect is responsible for generating the release branch. It is good practice to implement a code freeze when the architect is working on this. It is the facilitator’s responsibility to inform the community that the release branch has been created.

After the branch has been created, the architect will assemble the binaries. This should be automated as much as possible to avoid duplication of effort and to ease the process of creating a release. Usually, several distribution packages will be assembled at this stage for the different platforms the project supports. Since we are talking about open source projects, the project should also provide the source files within a binary distribution, including clear instructions on how to build the application. This encourages people to contribute by minimising the number of hoops they need to jump through in order to get to the source. Distributions should be made available as compressed files, typically zip files for Windows, tar.gz for Linux and an Apple Disk Image (.dmg file) for Mac users. At this stage, the documentation must also be checked and expanded where needed.

Publish and test the release candidate

The next phase of the release process is to make the release candidate available for testing. The packages can be distributed through the website, but it must be clear to users that it is not yet a final release. If the project is developing a web application, there may be a demo server available. If the release candidate is available on the demo server, it will be easier for less technical users to help test the release candidate. The availability of the release candidate should be announced widely on the publication channels to make sure that it gets tested by as many people and on as many different platforms as possible.

Towards the final release

Critical bugs or errors found in the release candidate will have to be fixed before the final release is created. This will involve applying a patch to the release branch and creating a new release candidate with a different version number, i.e. with the postfix -RC2. This process should be repeated until no more critical errors are found.

Once a release candidate has been fully tested, it needs approval to form the basis of the final release. This approval process will depend on the governance model adopted by the project. Once a release candidate has been approved, the architect will have to create the final release. It is good practice to cryptographically sign the final release so that its integrity can be checked by anyone who downloads it.

It is also a good idea to provide an installer for current and prospective users. This will allow them to get going quickly and easily and thus increase the chances that they will give the project feedback. Different platforms have different install packages. There are some cross-platform installers, which can be used, although they impose some limitations at present. However, the project should also make it as easy as possible for third parties to provide a platform-specific installer. Often this means nothing more than providing a good source distribution for them to work with.

The release must then be made available via the project’s distribution channels. These channels should be capable of handling the expected demand for the release. However, making a release available is not enough. The (prospective) users must also be made aware of the new release via news announcements. The facilitator is responsible for this.

Releases are a major news item for a project and should feature in the project’s blogs, RSS feeds and announcement list. The architect will have to update the project’s records in catalogues, app stores and similar lists. They will also need to update the DOAP file, and make sure all DOAP-powered catalogues are pinged.

Conclusion

Distributing releases is an important aspect of any open source project. It enables people to try out the project more easily and hence increases the chance of getting new contributors. Therefore we highly recommend the practice of releasing early. Although the process may seem complicated, once it is in place and it has been tried once or twice it will become easier. It is also easier to make a release before the codebase gets large, which is another reason why it makes sense to release early.

To help with the more technical bits of the release process, we have another document that describes some best practice guidelines along with a checklist.

Further reading

Links:

Related information from OSS Watch