0 Introduction

This document gives step-by-step instructions for cutting a release. These instructions assume that the component uses Maven to build the site, and either Maven or Ant to build the actual distributed files.

This documentation is pretty *nix-centric. Hopefully, release managers using windoz will be able to work out what they need to do for their platform. Any patches for windoz-based releases will be gratefully received.

Throughout this document, the example text consistently assumes that version 1.2 of component foo is being released by release manager rdonkin.

The starting point for this document is that all the preparations for the release have been completed, a release candidate created and a release [VOTE] successfully passed. Guidelines for these preparations can be found here.

In particular, it is assumed:

• The build version for the component has been updated to the release number in project.xml
• The build version for the component has been updated to the release number in build.xml if you have a hand-created Ant buildfile.
• The release directory tags/foo-1.2 has been created.

1 Build Distribution Files

Ensure commons-build is available as a sibling directory to the one you will be doing the build in. The most convenient way to do this is simply to check out commons-build into its usual place, then create a symbolic link to it:

	# we will be building in foo/tags/foo-1.2
        cd foo/tags
	# create a link from ./commons-build to wherever the trunk of
	# commons-build has been checked out
	ln -s {commons-build}/trunk commons-build
      

Now do a clean build of the binary distribution.

For Maven builds, it is assumed that there is a "dist" goal which creates source and binary distributions in subdirectory target/distributions.

      $ cd foo/tags/foo-1.2
      $ maven clean
      $ maven dist
    

For Ant builds, it is assumed that there is a "dist" target which creates source and binary distribution (.tgz, .zip) bundles.

      $ cd foo/tags/foo-1.2
      $ ant clean
      $ ant dist
    

Review the generated documentation and in particular ensure that the version number is correct.

2 Create Checksums

MD5 is the standard hash algorithm used by Apache to allow users to verify the integrity of releases. There are various applications which can be used to create md5 checksums.

For example md5sum (on Linux):

    $ md5sum -b commons-foo-1.2-src.tar.gz > commons-foo-1.2-src.tar.gz.md5
    

If possible, the format of the output should conform to the ASF repository standard. Currently, this is sum filename. For example:

    d1dcb0fbee884bb855bb327b8190af36 *commons-foo-1.2.tar.gz
    

Create md5 sums for the binary and source releases, both tarred and zipped versions. These should be stored in files whose names are formed by appending .md5. to each filename. So, you should end up with the following files:

    commons-foo-1.2-src.tar.gz.md5
    commons-foo-1.2-src.zip.md5
    commons-foo-1.2.tar.gz.md5
    commons-foo-1.2.zip.md5
    

3 Sign Releases

OpenPGP (RFC2440) compatible detached signatures needed to be created for all releases. Various applications can be used to create these signatures. For example, Gnu Privacy Guard.

See the Apache Release Signing FAQ for more information on release signing.

Example:

$ gpg --armor --output commons-foo-1.2-src.tar.gz.asc --detach-sig commons-foo-1.2-src.tar.gz    
You need a passphrase to unlock the secret key for
user: "Robert Burrell Donkin (CODE SIGNING KEY) <rdonkin@apache.org>"
1024-bit DSA key, ID B1313DE2, created 2003-01-15
    

Signatures for all varieties of release need to be create. The signature files should be named after the original with .asc suffixed.

$ gpg --armor --output commons-foo-1.2-src.tar.gz.asc --detach-sig commons-foo-1.2-src.tar.gz 
$ gpg --armor --output commons-foo-1.2-src.zip.asc --detach-sig commons-foo-1.2-src.zip
$ gpg --armor --output commons-foo-1.2.zip.asc --detach-sig commons-foo-1.2.zip
$ gpg --armor --output commons-foo-1.2.tar.gz.asc --detach-sig commons-foo-1.2.tar.gz
    

If this is the first release you personally have done for Commons, then your code signing public key must be added to the KEYS file for Commons. which is in the root of the Commons distribution directory (/www/apache.org/dist/commons/KEYS on people.apache.org). If this file is not present, it needs to be created.

4 Verify the Releases

• Verify signatures
  
  Use another user to verify the signatures. (The user must have your code-signing public key loaded into their key ring.) Here's an example using GnuPG:

  % gpg --verify commons-foo-1.2.tar.gz.asc commons-foo-1.2.tar.gz
  gpg: Signature made 03/01/03 19:34:31 GMT using DSA key ID B1313DE2
  gpg: Good signature from "Robert Burrell Donkin (CODE SIGNING KEY) <rdonkin@apache.org>"
  % gpg --verify commons-foo-1.2.zip.asc commons-foo-1.2.zip
  gpg: Signature made 03/01/03 19:34:05 GMT using DSA key ID B1313DE2
  gpg: Good signature from "Robert Burrell Donkin (CODE SIGNING KEY) <rdonkin@apache.org>"
  % gpg --verify commons-foo-1.2-src.zip.asc commons-foo-1.2-src.zip
  gpg: Signature made 03/01/03 19:33:42 GMT using DSA key ID B1313DE2
  gpg: Good signature from "Robert Burrell Donkin (CODE SIGNING KEY) <rdonkin@apache.org>"
  % gpg --verify commons-foo-1.2-src.tar.gz.asc commons-foo-1.2-src.tar.gz
  gpg: Signature made 03/01/03 19:32:56 GMT using DSA key ID B1313DE2
  gpg: Good signature from "Robert Burrell Donkin (CODE SIGNING KEY) <rdonkin@apache.org>"
        

• Check Sums
  
  . Verify md5 check sums. If you can, use another application to double check the sums. Here verifications are performed using openssl.

        % openssl md5 <commons-foo-1.2-src.tar.gz
        a76169177e7a9b58118bcd993aff4a5e
        % cat commons-foo-1.2-src.tar.gz.md5
        a76169177e7a9b58118bcd993aff4a5e
        
        % openssl md5 <commons-foo-1.2-src.zip
        ca0ae8330f666dd1626108346e36f799
        % cat commons-foo-1.2-src.zip.md5
        ca0ae8330f666dd1626108346e36f799
        
        % openssl md5 <commons-foo-1.2.tar.gz
        460fa7ad1e9ee2b5c4acab4971402395
        % cat commons-foo-1.2.tar.gz.md5 
        460fa7ad1e9ee2b5c4acab4971402395
        
        % openssl md5 <commons-foo-1.2.zip 
        d5f98c73f2450e09cc2b1af9509934f0
        % cat commons-foo-1.2.zip.md5
        d5f98c73f2450e09cc2b1af9509934f0
        

5 Upload Releases

Upload the following to your home directory on people.apache.org:

• all the release distributions
• the detached signature files (.asc) for these releases
• the md5 sums (.md5) for these releases
• the release notes. (If you're using maven, you may need to create a stripped down plain text version.)

A tip is to tar and gz everything and upload it all together:

    % scp release.tar.gz rdonkin@www.apache.org:~/
    release.tar.gz       100% |*********************************|   841 KB    00:46    
    % ssh -l rdonkin www.apache.org
    

Untar in a working directory (named release, say). Remember to make sure that the group is commons, that they are world readable and that they are group read-writable.

    chgrp commons release/*
    chmod 664 release/*       # rw-rw-r--
    

6 Move Releases Into Distribution Directories

Change directory to the distribution directory for your component:

    cd /www/www.apache.org/dist/commons/foo/
    

Move source distributions, their detached signatures and md5 sums into position. All source versions live in the source subdirectory.

      mv ~/release/commons-foo-1.2-src* source
    

Move the binary distributions, their detached signatures and md5 sums into position. All binary versions live in the binaries subdirectory.

    mv ~/release/commons-foo-1.2* binaries
    

Double check the permissions for binaries and source distributions.

7 Update Release Directory

Update README

The contents of the README.html are displayed at the bottom of the html showing the directory listing. This document should be updated to reflect the new release. If this document is not present, then copy one from an existing release directory and edit that.

Update the latest release number. Please also read through and correct any mistakes you find and fix other items (eg. urls) which need updating. If your component is missing a README.html then add a new one modeled on a copy in another component.

Copy the revised README.html into the binary and source directories, replacing any old versions.

Check KEYS file

Check the KEYS file located in the main release directory. This should contain all the public keys which have been used to sign Commons' releases. Make sure that this file exists and that it contains the public key you've used to sign these releases. (The KEYS file should give instructions about how to do this.)

Update Symbolic Links

Remove symbolic links to current distributions

    rm commons-foo-current*
    

Recreate links to current distribution

    > ln -s source/commons-foo-1.2-src.tar.gz commons-foo-current-src.tar.gz 
    > ln -s source/commons-foo-1.2-src.tar.gz.asc commons-foo-current-src.tar.gz.asc
    > ln -s source/commons-foo-1.2-src.tar.gz.md5 commons-foo-current-src.tar.gz.md5
    > ln -s source/commons-foo-1.2-src.zip commons-foo-current-src.zip
    > ln -s source/commons-foo-1.2-src.zip.asc commons-foo-current-src.zip.asc
    > ln -s source/commons-foo-1.2-src.zip.md5 commons-foo-current-src.zip.md5
    > ln -s binaries/commons-foo-1.2.tar.gz commons-foo-current.tar.gz
    > ln -s binaries/commons-foo-1.2.tar.gz.md5  commons-foo-current.tar.gz.md5
    > ln -s binaries/commons-foo-1.2.tar.gz.asc commons-foo-current.tar.gz.asc
    > ln -s binaries/commons-foo-1.2.zip commons-foo-current.zip
    > ln -s binaries/commons-foo-1.2.zip.md5 commons-foo-current.zip.md5
    > ln -s binaries/commons-foo-1.2.zip.asc commons-foo-current.zip.asc
    

Please test that these links function correctly!

Update RELEASE-NOTES

Replace the current RELEASE-NOTES.txt with the new release notes.

    mv ~/release/RELEASE-NOTES.txt .
    

Remove Obsolete Releases

If there are releases in the binary or source directory that are not expected to be frequently accessed (eg releases more than 2 years old) then these files should be deleted; this will cause the files to also be deleted from the mirrors and save them some diskspace as well as simplifying things for users. Note that the contents of the /www/www.apache.org/dist directory is regularly copied to /www/archive.apache.org/dist and from there transferred to host archive.apache.org. Deleting files from the standard distribution directories does not delete them from the archive dist directories (this is a copy, not an rsync) so users will still be able to access old files even when they are not available from the mirrors. The automatic transfer of files to the archive directory also means that you do not need to take any special actions to ensure your new files are made available on archive.apache.org.

8 Deploy jar, project.xml and license.html to Java-Repository

The ASF Java Respository is the home for distributions in jar format. Your jar file(s) should be placed in /www/people.apache.org/repo/m1-ibiblio-rsync-repository/commons-foo/jars on people.apache.org. The jars placed here will be rsynched (after some delay) to the public distribution repository on www.apache.org, as well as to the ibiblio repository. If available, your project.xml should be placed in /www/people.apache.org/repo/m1-ibiblio-rsync-repository/commons-foo/poms as the file commons-foo-1.2.pom. Ensure the version number matches the one inside the project.xml.

N.B. Remember to sign files placed in the ASF Java Respository.

The current html version of the Apache Software License needs to be in /www/people.apache.org/repo/m1-ibiblio-rsync-repository/commons-foo/licenses as the file license.html. If this file does not exist or reflects an out-of-date version, copy a current version from another component directory. There should also be a symlink named commons-foo.license in this directory. If this link does not exist, create it using

      ln -s license.html commons-foo.license 
    

Maven users can deploy release jars automatically using maven's jar plugin. See the project.properties.sample file in the commons-build directory for an example showing how to configure the necessary properties to support jar deployment using scp. A how-to showing how to get an apache ssh key set up can be found here. Given this setup,

      maven -Dmaven.repo.list=apache.releases -Duser.name=your-apache-id jar:deploy
    

will deploy the jar to the Apache Maven repository (with your user name as the value of the Built-By attribute in the manifest). Note that the maven jar plugin does not (yet) create or publish signatures, so if you use maven to deploy the jar, you need to manually sign it and copy the signature file separately to /www/people.apache.org/repo/m1-ibiblio-rsync-repository/commons-foo/jars. Make sure that the signature file has correct permissions and group ownership (matching the jar) after you copy it.

9 Test Main Site Downloads

You should now be able to get the new release from the main apache web site (http://www.apache.org/dist/commons/foo/).

Check the main directory:

1. Examine the directory listing page. At the bottom should be found the information you entered into the README.html. Please check that this is correct.
2. Check the KEYS file
3. Check the RELEASE-NOTES.txt
4. Download and verify the current distributions

Follow the links to the binaries and source directories. Check them in a similar manner.

10 Update Component WebSite

Publish Updated Website

On your own machine, ensure that the project.xml contains a <siteDirectory> tag that points to /www/commons.apache.org/foo, then run:

      maven -Dmaven.username=yourapacheid site:deploy
    

On people.apache.org, verify that the directory has been updated, and that the file and directory permissions are correct (readable by all, not writeable by world).

Note that the files are transferred to the real web site only every few hours, so it may be a while before you see your changes appear. However if you set your webbrowser's HTTP proxy to 209.237.227.195 port 80 and access http://commons.apache.org/ you should be able to see the changes immediately.

Perform Manual Fixups (if any)

It is quite nice for a component website to provide not just the latest javadocs and release notes, but also links to this information for previous releases. However Maven doesn't provide any way to do this. The usual solution is therefore for the component to arrange for its generated website to have some navbar links that point to somewhere that doesn't exist (at least not created by Maven), then manually put the missing info at the needed location after "maven site:deploy" has been run. If the component you are deploying has done such tricks, then you need to do the manual fixups now.

As an example, the foo component's website might have links for "1.1 release notes" and "1.1 javadoc" that point to "release11/RELEASE-NOTES.txt" and "release11/api"; in that case you'll need to create that release11 directory and install the old release notes and javadoc there.

Note that "maven site:deploy" will not delete any extra directories or files that were already there, so if there was a "release10" directory that is no longer referenced from the new website then you should delete that old directory.

11 Update Commons Web Site

If you are creating a component site for the first time, then you will need to update file commons-build/menus/components-items.ent in subversion and publish the updated commons site.

To update the commons site:

• check out the entire commons/trunks-proper directory (the build process needs all the other components checked out).
• cd commons/trunks-proper/commons-build
• edit downloads/downloads.xml as necessary
• maven site:generate
• ant -f build-downloads.xml
• maven -Dmaven.username=yourapacheid site:deploy
• check that the cgi scripts in the deployed site on people.apache.org are executable (if not chmod 775 the cgi scripts)

Note that the website is actually served from another machine, so it may take a few hours until those changes are transferred to the actual webserver host machine.

12 Create Announcements

Announce the availability of the new release. You can probably use the news item create earlier as a basis for the announcement body.

Please remember to give a brief description of you component. Please also remember to remind people about verifying the signatures. The subject should be something like [ANNOUNCEMENT] Foo 1.2 Released. Send this mail from your apache account. Please spell check the document!

This should go to (at least) the following mailing lists:

• announcements@jakarta.apache.org
• dev@commons.apache.org
• user@commons.apache.org

13 Post Release Update

That's it! The release is out there - but there is still some tidying up to be done.

• Update Build Version Number Update build number found in build.xml in the trunk. This should be updated to a dev release, eg change "1.2" to "1.3-dev"
• Update currentVersion Update currentVersion found in project.xml in the trunk. This should be updated to a SNAPSHOT release, eg change "1.2" to "1.3-SNAPSHOT"

14 Update JIRA

Check in JIRA for all bugs which have been marked LATER and reopen them. If you need some changes made to JIRA (for example, a new version number adding) and are unable to do so yourself, send an email to the dev list (dev at commons.apache.org).

Now is also an ideal time to have a go at fixing some of those bugs you marked as LATER.

15 Miscellaneous

There are some scripts available that help to automate some of these steps. In particular, see the following shell scripts in subversion under committers/tools/releases:

• sign_and_hash.sh (creates sigs and md5s)
• verify_sigs.sh (verifies sigs and checksums)
• symlinks.sh (creates symlinks)

16 DOAP file

Update the component's DOAP file with details of the released version:

    <release>
      <Version>
        <name>x.y.z</name>
        <created>yyyy-mm-dd</created>
        <revision>x.y.z</revision>
      </Version>
    </release>
    

Release information gets published on the Apache projects site.