This page aims to document our release process. It documents the release cycle, but also the steps required to make a release.
- 1. The release cycle
- 2. Steps for a release
- 2.1. Make sure Jenkins is all green
- 2.2. Generating the release notes
- 2.3. Running the release.sh script
- 2.4. Test the manual install in Jenkins
- 2.5. Build the Debian packages
- 2.6. Test the upgrade in Jenkins
- 2.7. Creating release nodes on Drupal.org
- 2.8. Build the release in Jenkins again
- 2.9. Publish the Debian packages
- 2.10. Publish the release notes widely
1. The release cycle
In general, each major Aegir release comprises a simultaneous release of all the modules that are part of the project. We generally go through several testing releases (alphas, betas & RCs) before doing the first stable release on a branch.
- First an alpha is released to test new functionalities and to accomplish the goals decided in the Project Roadmap for that major version. Example:
- When we have covered most of the functionalities outlined in the roadmap, we push out beta releases until no more critical issues show up. This is generally considered a soft feature freeze. Example:
- Then we go into full feature freeze and release a first release candidate (RC). Then a stable release branch is created, and the development branch is kept opened for development for the next stable release. This is generally considered a soft API freeze. Release candidates are made as long as critical bugs are found. Example:
0.4-rc1, freeze announcement
- Once the development branch has no known critical bugs, the stable release is announced. From there on only critical fixes (security, critical performance and critical bugfixes) are committed to the stable branch, and stable releases are published (without alpha/beta/RC) directly on the stable branch. The stable branch is in full API freeze. New features are generally committed to the development branch.
See also the tag and branch naming convention.
2. Steps for a release
For the specifics of release naming conventions and the cycle, see the branch naming convention.
2.1. Make sure Jenkins is all green
Look into Jenkins to see if all tasks have been performed without errors since the last commit. If there is an error, fix it before the release.
2.2. Generating the release notes
We build complete release notes for every release. Those are made up of a summary of the release, an outline of key changes, of known issues, install and upgrade instructions and a full list of bugfixes and new features.
We have a handy bookmarklet that takes the list of issues and build a release-notes-ready list:
The developers then proceed to format/edit the list of fixes as well as list other significant information/changes for this release. These notes end up becoming the Release Notes for the release, which are also entered in the
debian/changelog file by the script below.
2.3. Running the release.sh script
Each time we make a new release, we run a script called
release.sh in provision.
This script should only be used by the core dev team when doing an official release. If you are not one of those people, you probably shouldn't be running this.
This script does all the 'hard' work in that it doesn't forget all the very many places to edit version numbers etc of relevant documentation and other scripts. This includes install.sh.txt and upgrade.sh.txt.
Paraphrasing from the script itself:
The following operations will be done:
0. prompt you for a debian/changelog entry
1. change the makefile to download tarball
2. change the upgrade.sh.txt version
3. display the resulting diff
4. commit those changes to git
5. lay down the tag
6. revert the commit
7. (optionally) push those changes
The operation can be aborted before step 7. Don't forget that as
long as changes are not pushed upstream, this can all be reverted (see
git-reset(1) and git-revert(1) ).
So in short, this sums up as:
sh release.sh 1.7
git tag 6.x-1.7
git push origin 6.x-1.7
Notice how we just provide the Aegir release number (
1.7), not the Drupal branch (
6.x), which is hardcoded in the script to remove potential confusion.
2.3.1. Optional: new Eldir release
If we do a major release (say a point zero release), we may want to make a new release of the theme (Eldir). This can also be performed if there enough new changes on the theme to warrant a new release on its own.
To do a new release of Eldir:
- tag and push the tag
- update the version to fetch in hostmaster.make
- create a release node for Eldir
2.4. Test the manual install in Jenkins
Before making a full release, test the release in Jenkins. To do so, start a build of the launch the S_aegir_6.x-1.x_install job with the following parameters:
- the right release as the
DRUSH_VERSIONto match what is required for this release.
If the build fails, delete the remote tags (using
git push origin :6.x-1.7, for example), fix the bugs and start again.
2.5. Build the Debian packages
If you need to move the tags again, you will need to clear the testing archive using the R clear repo job, with the testing argument.
You can also build and upload the package yourself as explained in those detailed instructions. We first upload the package to the
testing distribution, and it gets migrated down into
stable after tests.
2.6. Test the upgrade in Jenkins
Once both of those taska have executed successfully, you can test the upgrade of the Debian packages by running the following Jenkins job:
2.7. Creating release nodes on Drupal.org
Once the tags are pushed and release notes published, we create a release node with an excerpt of (and a link to) the release notes so that tarballs are created and issue queue versions updated.
Note: this could be automated with the right stuff on Drupal.org.
2.8. Build the release in Jenkins again
At this point, it's possible that the tarballs on Drupal.org were not created properly. We want to test the real procedure, so run a your build again, but choose 'package' as the
AEGIR_FETCH_MODE. S_aegir_6.x-1.x_install job
2.9. Publish the Debian packages
Finally, when the Debian packages are tested you will need to pull them into the stable release channel:
2.10. Publish the release notes widely
Once all this is done and the tarballs are generated, the release notes are published in:
- The handbook (this is where the release notes live!)
- A link to the release notes on the frontpage block
- An event in the calendar
- A discussion post (don't forget to make it 'sticky' & remove stickiness from the previous announcement)
- Update the version in the script upgrade page
- The topic of the IRC channel
- The aegir-announce mailing list
- Twitter as @aegirproject