The Subversion Release Procedure

If you are the current Release Manager for the Subversion project, or aspire to be, you should read and follow this procedure.

$LastChangedDate: 2006-04-03 18:57:54 +0200 (Mon, 03 Apr 2006) $

Table of Contents

  1. Being the Release Manager
  2. Creating and maintaining release branches
  3. Porting changes to release branches
  4. Managing the CHANGES file
    1. Writing the initial content for a branch
    2. Adding content for patch release
  5. Preparing to roll a release
  6. Rolling a release
  7. Blessing a release
  8. The actual releasing
  9. After a release has been made

Being the Release Manager

The role of the Release Manager in the Subversion project is to handle the process of getting code stabilized, packaged and released to the general public. If we were building planes, the RM would be the guy looking at the construction checklists, painting the airline logo on the fuselage, and delivering the finished unit to the customer.

As such, there is no real development associated with being an RM. All the work you have to do is non-coding: coordinating people, centralizing information, and being the public voice announcing new stable releases. A lot of the tasks that the RM has to do are repetitive, and not automated either because nobody has broken down and written the tools yet, or because the tasks require human validation that makes automation a little superfluous.

You may be thinking at this stage that the RM's duty is unglamorous, and you are kinda right. If you are looking for a position within the project that will bring fame and fortune, you're better off implementing stuff that really needs to be done on trunk. If you're looking for something that really helps people who don't care about releases focus on code, then RMing is for you.

So, you are the Release Manager. What do you need to do? This is what the rest of this document is about.

Creating and maintaining release branches

A new release branch is created for each new major and minor release. So, for example, a new release branch is created when preparing to release version 2.0.0, or version 1.3.0. However, when preparing to release 1.3.1 (a patch-version increment), the release branch created at the time of 1.3.0 is used.

If you are preparing for a patch release, then there is no release branch to create. You just pick up where you left off in the current minor version series release branch.

The time at which a new release branch needs to be created is fuzzy at best. Generally, we have a soft schedule of releasing a new minor version every 6 months. So, approximately 4 months after the previous minor release is a good time to start proposing a branch. But remember that this is flexible, depending on what features are being developed.

Once people agree that a new release branch should be made, the Release Manager creates it with the following procedure (substitute A.B with the version you're preparing, eg. 1.3, or 2.0):

Porting changes to release branches

Once a release branch has been created, no development ever takes place there. The only changes permitted are ones made to various bookkeeping files such as STATUS, and changes merged in from trunk.

The protocol used to accept or refuse the merging of changes from trunk is of interest to all Subversion developers, and as such is documented in the release stabilization section of the hacking guide.

Managing the CHANGES file

The CHANGES file is the project changelog file. Before a release, it must be brought up to date to list all changes since the last release.

For patch-releases, this is fairly easy: you just need to walk through the commit logs for the branch since the last "golden" revision, and note all interesting merges. For minor and major releases, this is more complex: you need to traverse the commit log on trunk since the last release branch was forked, and make note of all changes there. It's the same procedure, but a lot longer, and somewhat more complex as it involves filtering out changesets that have already been backported to previous release branches and released from there.

Remember that CHANGES should always be edited on trunk and then merged over to the release branch(es) when necessary. It is very important that all changes of all releases be documented in the CHANGES file on trunk, both for future reference and so that future release branches contain the sum of all previous change logs.

Keep the bullet point for each change concise, preferably no more than one line long. Sometimes that can be a challenge, but it really adds to the overall readability of the document. Think to yourself: If it takes more than one line to describe, maybe I'm getting too detailed?

Writing the initial content for a branch

Run svn log -rHEAD:BRANCH_POINT http://svn.collab.net/repos/svn/branches/A.B.x,where BRANCH_POINT is the revnum where the previous major/minor release was branched off of the trunk. This should give you every change ever made to the A.B.x line, including backports made to the A.B.x branch. You then need to remove logs of changes that have already been released in micro releases of the previous major/minor branch. Run svn log -q --stop-on-copy on the previous release branch, and then write a script to parse the revnums and remove them from your primary log output. (Karl and Ben used to use emacs macros to do that, but suggest that we write a more general script.)

Read that log from oldest to newest, summarizing points as you go. The trick is to know what level of detail to write at: you don't want to mention every tiny little commit, but you don't want to be too general either. Set your filter-level by reading through a few pages of the CHANGES file before starting on the new section, just to keep things consistent.

Adding content for patch release

As part of release stabilization, CHANGES should be updated as bug fixes are ported to the release branch. Generally, if you merge a revision or group of revisions (i.e., an item in STATUS) to the release branch, you should also add an item to CHANGES on trunk, following the same guidelines outlined above. This list will then be merged to the release branch when a patch release is made.

Preparing to roll a release

So, a release branch has stabilized, and you are gearing up to roll the release. Before you can actually roll the archives, you need to set up a white-room rolling environment. This environment must contain pristine versions of some build tools, as well as all the relevant dependancies and other stuff that gets bundled into a release tarball.

You need to grab vanilla source tarballs of the following build tools before proceeding:

It is important that you do not use distribution shipped versions of this software as they are often patched in ways that are not portable. The version numbers given above should normally be reconsidered and increased to the latest stable upstream release in the time leading up to an A.B.0 release. Changing the version within an A.B.x series should only be done with careful considereration.

Also grab the following source tarballs, parts of which will be bundled in the Subversion release packages:

Once you have all this, you can start the following procedure. When it is done, you will have a build environment ready to roll tarballs.

Autoconf, Libtool and SWIG: Pick a directory to contain your special build tools for Subversion RM duties - for example /opt/svnrm. Configure, build and install the three pieces of software with --prefix=/opt/svnrm, and remember, whenever you run dist.sh to be sure that /opt/svnrm/bin is at the front of your PATH.

Dependency source preparation: You should create two directories which will hold the dependencies which will be repackaged with Subversion, one for Unix and one for Win32. You might, for example, choose /opt/svnrm/unix-dependencies and /opt/svnrm/win32-dependencies. Within the Unix one, you must unpack the Unix APR and APR-util tarballs, and the Neon and zlib tarballs, and then rename each top level directory so it does not contain a version number, resulting in a directory containing four directories: apr, apr-util, neon and zlib. Within the Win32 one, you must unpack the Apache HTTP Server zipfile, move the apr, apr-util and apr-iconv directories from the srclib directory of the httpd zipfile into the dependency directory, and delete the rest of the httpd extract. You must then copy the neon and zlib directories from the Unix dependency directory into the Win32 one too. Do not use symlinks, dist.sh does not support them.

Rolling a release

Before rolling, first make sure that the latest version of the CHANGES file from trunk is merged into the release branch, and that the date at the top of CHANGES matches the planned release date of the tarball.

Build the tarballs: From within your Unix dependency directory, run:

PATH="/opt/svnrm/bin:$PATH" ./dist.sh -v X.Y.Z -r 1234 -pr branches/X.Y.Z

Watch dist.sh's output to make sure everything goes smoothly; when it's done, you'll have tarballs in the cwd.

Build the zipfiles: From within your Win32 dependency directory, run:

PATH="/opt/svnrm/bin:$PATH" ./dist.sh -v X.Y.Z -r 1234 -pr branches/X.Y.Z -zip

Watch dist.sh's output to make sure everything goes smoothly; when it's done, you'll have zipfiles in the cwd.

Test one or both of the tarballs:
 
    a) tar zxvf subversion-X.Y.Z.tar.gz;  cd subversion-X.Y.Z
    b) ./configure
 
       See INSTALL, section III.B for detailed instructions on
       configuring/building Subversion.
 
       If you installed Apache in some place other than the default, as
       mentioned above, you will need to use the same
       --prefix=/usr/local/apache2 option as used to configure Apache.
 
       You may also want to use --enable-mod-activation, which will
       automatically enable the required Subversion modules in the
       Apache config file.
 
    c) make
    d) make check
    e) make install (this activates mod_dav)
    f) make davcheck
 
       For this, start up Apache after having configured according to
       the directions in subversion/tests/cmdline/README.
 
       Make sure, that if you maintain a development installation of
       apache, that you check the config file and update it for the
       new release area where you're testing the tar-ball.
 
       (Unless you rename the tree which gets extracted from the
       tarball to match what's in httpd.conf, you will need to edit
       httpd.conf)
 
    g) make svncheck
 
       First, start up svnserve with these args:
 
          $ subversion/svnserve/svnserve -d -r \
            `pwd`/subversion/tests/cmdline
 
       -d tells svnserve to run as a daemon
       -r tells svnserve to use the following directory as the
          logical file system root directory.
 
       After svnserve is running as a daemon 'make svncheck' should run
 
    h) Then test that you can check out the Subversion repository
       with this environment:
 
          subversion/svn/svn co https://svn.collab.net/repos/svn/trunk
 
    i) Verify that the perl and python swig bindings at least compile.
       If you can't do this, then have another developer verify.
 
       (see bindings/swig/INSTALL for details)
 
       Ensure that ./configure detected a suitable version of swig,
       perl, and python.  Then:
 
          make swig-py
          make check-swig-py
          sudo make install-swig-py
 
          make swig-pl
          make check-swig-pl
          sudo make install-swig-pl
 
    j) Verify that the javahl bindings at least compile.
       If you can't do this, then have another developer verify.
 
       (see bindings/java/javahl/README for details)
 
       Ensure that ./configure detected a suitable jdk, and then
       possibly re-run with '--enable-javahl' and '--with-jdk=':
 
          make javahl
          sudo make install-javahl
          make check-javahl

Use GnuPG to sign release:

    gpg -ba subversion-X.Y.Z.tar.bz2
    gpg -ba subversion-X.Y.Z.tar.gz
    gpg -ba subversion-X.Y.Z.zip
    gpg -ba subversion-deps-X.Y.Z.tar.bz2
    gpg -ba subversion-deps-X.Y.Z.tar.gz
    gpg -ba subversion-deps-X.Y.Z.zip

Subversion Operations

Create the tag with the svn_version.h that reflects the final release. You do this by updating your working copy to the release revision, 1234 in the example below. Run svnversion to verify that you do not have a mixed working copy or modified working copy, i.e. svnversion outputs only the release revision (not 1234:1235 or 1234M). Then place the svn_version.h.dist file in place in the working copy and copy from the working copy to the tag URL. For example:

    svn up -r 1234
    svnversion .
    cp svn_version.h.dist subversion/include/svn_version.h
    svn cp . \
           https://svn.collab.net/repos/svn/tags/X.Y.Z \
           -m "Tagging release X.Y.Z with svn_version.h matching tarball"

Note: Please always make a tag, even for release candidates.

Bump the svn_version.h for the original branch. If you just did 1.0.2 then svn_version.h should have the proper values for 1.0.3 and so on.

Blessing a release

The actual releasing

Upload the tarballs to http://subversion.tigris.org/downloads/.

The RM will be given details on how to do this via private channels.

Update Tigris "Documents & files" area

Update the links to the tarballs in the Documents & files Tigris webapp.

  1. Log into Tigris
  2. Click on 'Documents & files'.
  3. Navigate to the 'subversion/Releases/Source code/' folder.
  4. For each of the 12 files:
    1. Click on the 'Add new file' link.
    2. Fill in the following fields:
      • Name: <file name>
      • Status: Stable
      • Description: (one of:)
        • Subversion release X.Y.Z (MD5: <md5sum of tarball>)
        • Subversion dependencies X.Y.Z (MD5: <md5sum of tarball>)
        • PGP Signatures for Subversion release X.Y.Z.
      • Contents: (choose 'Link', then enter:) http://subversion.tigris.org/downloads/<file name>
    3. Click Submit.

Announcements

Write a release announcement, referring to previous ones for guidance. Remember to include the URL and MD5 checksums in the announcement!

Post a project news item here. If the link reads "Suggest an announcement" instead of "Add new announcement", then you do not have the required permission - ask to be granted the 'Release Manager' Tigris role. Note that the Tigris news items are in HTML format not plain text.

Send an announcement to dev@, users@, and announce@ lists. Ensure that your mailer doesn't wrap the URLs over multiple lines.

You should also notify Freshmeat of the new release. For a regular final release, this involves adding the new release to the "Stable" Freshmeat project branch (click the "add release" link in the top navigation bar); alpha, beta, and RC releases get filed the say way, but under the "Development" branch. You need to be listed as a release manager or admin for the Subversion project on Freshmeat. Contact one of the folks who are already listed if you need access. Your submission will also be tweaked by the freshmeat crew before it goes public.

Update the website

  1. Edit the www/project_status.html file appropriately in /trunk *NOT* in the release branch and commit. Remember edit a search term at the end of release's issue link.
  2. Update the best available version on the front page and at the top of www/getting.html
  3. Update the "Latest Release" section of www/index.html to point to the new announcement.
  4. Commit the modifications.

If you've made it this far, go and enjoy your $favorite_beverage now.

After a release has been made

When someone with administrative access to svn.collab.net has time available, they will upgrade it to the latest release or release candidate. (This person is not usually the release manager.)