Apache Commons logo

Publishing The Release - Step By Step

Introduction

This document gives step-by-step instructions for publishing a release. These instructions assume that the component uses Maven to build the site.

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

In particular, it is assumed:

  • The signed release candidate source and binary distributions and release notes are available in https://dist.apache.org/repos/dist/dev/commons/foo.
  • The maven artifacts associated with the release are available in a closed Nexus staging repository.

1 Move Releases Into Distribution Directories

The distribution area of commons releases is populated from https://dist.apache.org/repos/dist/release/commons/ via svnpubsub. In order to publish the release, you must move the distributions files from dev to release.

You can perform multiple svn mv operations (with or without local working copies) or you can use svnmucc, for example:

      svnmucc -U https://dist.apache.org/repos/dist \
          mv dev/commons/foo/RELEASE-NOTES.txt release/commons/foo \
          mv dev/commons/foo/binaries/commons-foo-1.2-bin.tar.gz release/commons/foo/binaries \
          mv dev/commons/foo/binaries/commons-foo-1.2-bin.tar.gz.asc release/commons/foo/binaries \
          mv dev/commons/foo/binaries/commons-foo-1.2-bin.tar.gz.md5 release/commons/foo/binaries \
          mv dev/commons/foo/binaries/commons-foo-1.2-bin.tar.gz.asc release/commons/foo/binaries \
          mv dev/commons/foo/binaries/commons-foo-1.2-bin.zip release/commons/foo/binaries \
          mv dev/commons/foo/binaries/commons-foo-1.2-bin.zip.asc release/commons/foo/binaries \
          mv dev/commons/foo/binaries/commons-foo-1.2-bin.zip.md5 release/commons/foo/binaries \
          mv dev/commons/foo/binaries/commons-foo-1.2-bin.zip.asc release/commons/foo/binaries \
          mv dev/commons/foo/source/commons-foo-1.2-src.tar.gz release/commons/foo/source \
          mv dev/commons/foo/source/commons-foo-1.2-src.tar.gz.asc release/commons/foo/source \
          mv dev/commons/foo/source/commons-foo-1.2-src.tar.gz.md5 release/commons/foo/source \
          mv dev/commons/foo/source/commons-foo-1.2-src.tar.gz.asc release/commons/foo/source \
          mv dev/commons/foo/source/commons-foo-1.2-src.zip release/commons/foo/source \
          mv dev/commons/foo/source/commons-foo-1.2-src.zip.asc release/commons/foo/source \
          mv dev/commons/foo/source/commons-foo-1.2-src.zip.md5 release/commons/foo/source \
          mv dev/commons/foo/source/commons-foo-1.2-src.zip.asc release/commons/foo/source \
          -m "Publish commons-foo 1.2 Release"
    

2 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.

The README must be https://dist.apache.org/repos/dist/release/commons/foo/README.html

Update the latest release number. Please also read through and correct any mistakes you find and fix other items (eg. urls) which need updating.

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 gives instructions on how to do this.

3 Deploy Maven Artifacts

Login to the Nexus web interface, select your staging repository and promote it.

The files placed here will be mirrored (after some delay) to the public distribution repository on http://repo1.maven.org/maven2/.

4 Create Subversion Tag for the Final Release

Copy the release candidate tag in subversion to a name without RC in its name.

5 Test Main Site Downloads

Wait until the release files are available from the main Apache web site (http://www.apache.org/dist/commons/foo/), then confirm things are good.

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, the following might help committers/tools/releases/verify_sigs.sh.

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

6 Update Component Build and Website

  • Update trunk version Update current version found in pom.xml in the trunk if it has not already been done. This should be updated to a SNAPSHOT release, eg change "1.2" to "1.3-SNAPSHOT". If the component maintains an Ant build and the version is specified in build.xml, make sure to update this as well.
  • Publish the website, per the instructions here.

7 Create Announcements

Announce the availability of the new release.

Please remember to give a brief description of your 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!

Wait to send the release announcement until you have verified that

  1. The release artifacts are available on the mirrors.
  2. The component website including the updated download page has been updated on the public site http://commons.apache.org/proper/foo.
  3. If the component publishes maven artifacts, these artifacts have been replicated to the central maven repo at repo1.maven.org. (Clear your local repo of the release artifacts and either activate the clirr report with the updated version info or update a local project with a dependency to the new release version to get maven to try to download the release artifacts. Or just access repo1 using a web browser.)

The release announcement should go to (at least) the following mailing lists:

  • announce@apache.org
  • dev@commons.apache.org
  • user@commons.apache.org

8 Update Main Website

9 Post Release Cleanup

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

  • Remove Obsolete Releases
    Unless old versions are especially required, remove them from the dist directory. 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 http://www.apache.org/dist directory is regularly copied to http://archive.apache.org/dist. Deleting files from the standard distribution directories on https://dist.apache.org/repos/dist/release/commons/ does not delete them from the archive dist directories so users will still be able to access old files even when they are not available from the mirrors.
  • Update JIRA Mark the release as released in the JIRA project admin and CLOSE all issues RESOLVED in this release. Make sure the FIX VERSION for all issues closed with this release is set correctly to this version. If this has not already been done, create a JIRA version for the next release.
  • Update DOAP file Update the component's DOAP file and add a new entry 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> 
  • Update changes.xml If the component uses the maven changes plugin to maintain its changelog, fill in the release date for the just released version and create a new release element for the next release.