Release process

Tagged:

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

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: 0.4-alpha1, 0.4-alpha15
  • 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: 0.4-beta1
  • 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:

javascript:(function(){x%20=%20open().document;$(".views-field-title a").each(%20function()%20{%20x.write('* [' + $(this).attr('href').replace(/\/node\//, '#') + ': ' + $(this).text()+'](http://drupal.org'+$(this).attr('href')+ ')<br%20/>')%20})})()

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:

cd provision
sh release.sh 1.7
cd ../hostmaster
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:

  1. tag and push the tag
  2. update the version to fetch in hostmaster.make
  3. 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 AEGIR_VERSION parameter
  • the DRUSH_VERSION to match what is required for this release.
  • 'git' as the AEGIR_FETCH_MODE

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

Build the package and upload to http://debian.aegirproject.org/. Jenkins can build a Debian package for you with the S_aegir-debian-official job.

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 the package yourself as explained in those detailed instructions.

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:

http://ci.aegirproject.org/view/Upgrades/job/U%20aegir%206.x-1.x%20deb%2...

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.

This needs to be done in the hostmaster and provision projects on Drupal.org.

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:

http://ci.aegirproject.org/view/Release%20scripts/job/R%20repo%20pull/

2.10. Publish the release notes widely

Once all this is done and the tarballs are generated, the release notes are published in:

Optionally, blog posts on koumbit.org, mig5.net, and elsewhere may go into further detail about significant changes, screencasts etc.