What is Release Management?
Release Management is the process of building, packaging, and deploying of software for consumption. Many projects think they do not need to make releases until they are complete, this is not the case, as discussed in ReleaseEarlyReleaseOften.
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, however, as a project matures they can be separated out and delegated to different team members. This document discusses the roles in isolation in order to facilitate this.
It is a process that is controlled by a Release Manager. A Release Manager is:
- Architect – helps to identify, create, and implement the release process
- Manager - of the release process
- Facilitator – is the liaison between all stakeholders in a release
The stakeholders in a release include:
- Developers of the software
- Quality Assurance engineers
- Users of the released software
- Press and marketing contacts
- making a release has legal consequences
- users tend to interact with a project through its releases
Software releases require much more process than many other activities in software development. Process is necessary to ensure that all legal issues are addressed and that the quality of a release is sufficient be useful to users. This does not mean that a release must be complete (what software ever is) or that it must be bug free (yeah right!). It merely means that each release is well documented with respect to its status and users therefore know what they are getting.
Building a version of the software to be considered for release should be a fairly easy process since the software build ought to be an almost fully automated process. However, some aspects of the release build process will be difficult if not impossible to automate.
There are likely to be multiple release candidates packages, for different platforms.
Each release candidate is identified by a version number.
Before becoming an official release a build of the software will undergo a phase of prerelease testing. Often the package being tested will be indicated in the version number, for example, it may be designated as a release candidate with the letters RC1, for release candidate one.
Once a release candidate has been fully tested it will be approved for release. This approval process will be dependent on the governance model adopted by the project.
Signing of the release package. Users need to be assured of the integrity of the downloaded package. Therefore the release should be signed.
Once a release has been approved it must be made available to users via the projects distribution channels. These channels should be capable of handling the expected demand for the release.
Of course, making a release available is not enough. They must be made aware of the new release via news announcements.
The list of open issues needs to be analysed prior to release. Decide which issues will be resolved in this release and which should be moved to a later release. Do not attempt to fix all issues in any given release. This is a sure way of ensuring the release never happens. Any issues that are to be delayed should be moved to a later release in your 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 this release you should record this in your release documentation so that users will get a clear indication of slippage in the schedule.
Remember slippage of individual is not a bad thing, it is clear indicator to your users about what they can expect in the next release. This is open source, if a user wants to see an issue fixed in time for the next release they should provide a patch. By clearly indicating that the active developers will not address any given issue in a given release users can decide just how important it is to them and, where necessary, provide additional resources to the project.
The review of issues should not be limited to the run-up to release management. It should be a part of the daily routine of software development, however, in the run up to a release it is sensible to review issues in order to ensure the release will ready on schedule.
Documentation should be proof read and tested (in the case of things like install instructions).
Users expect to find a minimal set of documentation in the root directory of a release. This section describes those documents.
The README.txt is where the users will first go once they download you distribution. This should give the bare minimum of information on how to understand the release and how to start working with it. At the very least it should include getting started instructions and details of where to find more information.
The release notes contains a description of the project and an overview of what this new release provides. It does not provide detailed change information but it does provide 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 out 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 document describes the bug fixes, new features and API changes found in this release. Where the document
This document is usually the first point of call for users upgrading from a previous version.
SVN logs can be used to collect changes, however this can result in too detailed a view of things, i.e. a spelling correction in the docs does not warrant an entry in the changes document. This is a good opertunity to reinforce the need for good commit messages, that is each commit should be atomic and messages should be clear and concise.
Some tools provide a means for managing change documents independently of SVN. This allows much more control over what appears in your changes document and so makes the document more useful to users.
LICENCE and NOTICE
You should have a licence file in your root directory that clearly indicates the licence in use. You may also require a NOTICE text. The existence of a NOTICE text dictated by the licences of projects you are dependent upon.
- Should include LICENCE and NOTICE. Note this
- Should include a standards compliant MANIFEST.
A release often comes in a number of distribution packages. Since this is an open source project you should always have a source distribution that contains clear instructions on how to build the application. Compiled languages should also provide a binary distribution in which the application has already been built. In most instances you should also provide the source files within a binary distribution. This encourages people to contribute by minimising the hoops they need to jump through in order to get to the source.
Distributions should be made available as compressed files, typicaly zip files for windows and tar.gz for Linux.
It is also a good idea to provide an installer for your users. This allows them to get going quickly and easily and thus maximises the chances that they will give you feedback.
Different platforms have different install packages, there are some cross platform installers and you may choose to use one of this and live with some of the limitations they present. However, you 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.
It is of particular importance that released code is clean. It is good practice to check the provinance of any source documents which do not have licence headers. Check that dependencies (and in particular those dependencies that ship in the distribution) comply with Apache policy. Legal policy and interpretation changes from time to time so it is worth investing a little time reading again the legal release material.
Tag Releases in Version Control
All releases should be built from a tag in your version control system. It is occasionally necessary to rebuild releases many years later. Tagging is a reliable way to do this. So, every release and candidate should be tagged.
It is useful to adopt a reasonable naming convention when tagging releases. This allows release tags to be recognized 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 in which can 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.
If svn:externals is used, check carefully that a tag is referenced. This ensure that all the source for the release is fixed. If the target of a svn:externals changes then the release will no longer be complete reproducable.
It is important to review all library dependencies as part of the release process for compliance with your project policy. A list should be compiled of the project's dependencies, those shipped as binary libraries and those shipped as source document together with the licences for those dependencies. These lists should be checked against the latest policy documents.
Releases as Advertising
Releases are a major news item for your project. Be sure to blog about it, put it in your project RSS feeds, send to your announcements list. Update your records in catalogues such as freshmeat.net, update your DOAP file and ping any DOAP powered catalogues.
The checklist below is useful in ensuring 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.
- Check compressed distributions unpack correctly
- Check documentation is readable
- Check distributed libraries
- Check licences for libraries are distributed together with any applicable NOTICEs
- Check that licences comply with project policy
- Check that LICENCE and NOTICE documents contain required sections
- Check copyright notices:
- Licences missing from source files
- Source files with other licences which are not mentioned in LICENCE
- Check all headers comply with project policy
- Distributed Artifacts
- Check LICENCE and NOTICE files.
- Check a meaningful readme.txt document is present
- Source Distribution
- Check a meaningful readme.txt document is present
- Check build instructions exist and that source builds using these instructions
- Check licence headers are correctly applied
- Check for version control files
- Check that source is exported from tag
- OpenPGP keys
- Check KEYS file contains signing key
- Check key has been uploaded to regular public key servers