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 \
          rm release/commons/foo/RELEASE-NOTES.txt \
          mv dev/commons/foo/RELEASE-NOTES.txt release/commons/foo/RELEASE-NOTES.txt \
          mv dev/commons/foo/binaries/commons-foo-1.2-bin.tar.gz release/commons/foo/binaries/commons-foo-1.2-bin.tar.gz \
          mv dev/commons/foo/binaries/commons-foo-1.2-bin.tar.gz.asc release/commons/foo/binaries/commons-foo-1.2-bin.tar.gz.asc \
          mv dev/commons/foo/binaries/commons-foo-1.2-bin.tar.gz.md5 release/commons/foo/binaries/commons-foo-1.2-bin.tar.gz.md5 \
          mv dev/commons/foo/binaries/commons-foo-1.2-bin.tar.gz.sha1 release/commons/foo/binaries/commons-foo-1.2-bin.tar.gz.sha1 \
          mv dev/commons/foo/binaries/commons-foo-1.2-bin.zip release/commons/foo/binaries/commons-foo-1.2-bin.zip \
          mv dev/commons/foo/binaries/commons-foo-1.2-bin.zip.asc release/commons/foo/binaries/commons-foo-1.2-bin.zip.asc \
          mv dev/commons/foo/binaries/commons-foo-1.2-bin.zip.md5 release/commons/foo/binaries/commons-foo-1.2-bin.zip.md5 \
          mv dev/commons/foo/binaries/commons-foo-1.2-bin.zip.sha1 release/commons/foo/binaries/commons-foo-1.2-bin.zip.sha1 \
          mv dev/commons/foo/source/commons-foo-1.2-src.tar.gz release/commons/foo/source/commons-foo-1.2-src.tar.gz \
          mv dev/commons/foo/source/commons-foo-1.2-src.tar.gz.asc release/commons/foo/source/commons-foo-1.2-src.tar.gz.asc \
          mv dev/commons/foo/source/commons-foo-1.2-src.tar.gz.md5 release/commons/foo/source/commons-foo-1.2-src.tar.gz.md5 \
          mv dev/commons/foo/source/commons-foo-1.2-src.tar.gz.sha1 release/commons/foo/source/commons-foo-1.2-src.tar.gz.sha1 \
          mv dev/commons/foo/source/commons-foo-1.2-src.zip release/commons/foo/source/commons-foo-1.2-src.zip \
          mv dev/commons/foo/source/commons-foo-1.2-src.zip.asc release/commons/foo/source/commons-foo-1.2-src.zip.asc \
          mv dev/commons/foo/source/commons-foo-1.2-src.zip.md5 release/commons/foo/source/commons-foo-1.2-src.zip.md5 \
          mv dev/commons/foo/source/commons-foo-1.2-src.zip.sha1 release/commons/foo/source/commons-foo-1.2-src.zip.sha1 \
          -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 is the first release of the component or if this document is not present, then copy one from an existing release directory and edit that. The README must be located at https://dist.apache.org/repos/dist/release/commons/foo/README.html. Furthermore symbolic links have to be created to point from the binaries and source folders to the HEADER.html and README.html files:

      cd binaries
      ln -s README.html ../README.html
      ln -s HEADER.html ../HEADER.html
      cd ../source
      ln -s README.html ../README.html
      ln -s HEADER.html ../HEADER.html
    

Then update the latest release number in README.html. 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 https://repo.maven.apache.org/maven2/.

4 Create SCM Tag for the Final Release

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

    svn cp -m "Release commons foo 1.2 based on RC 1" \
      https://svn.apache.org/repos/asf/commons/proper/foo/tags/foo-1.2-RC1 \
      https://svn.apache.org/repos/asf/commons/proper/foo/tags/foo-1.2
    

Make sure you have the latest changes on the master branch and the release branch:

    git checkout release
    git pull origin master
    git pull origin release
    

Now create the final tag (note that it should follow the same naming convention as for the release candidate, except for dropping the "rc" suffix and prepending the "rel/" string), bump the version number to the next development version, commit the new version and merge the release branch back into the master branch, so that the master branch also has the new development version:

    git tag -s rel/commons-foo-1.2 -m "Create Commons Foo 1.2 release tag"
    mvn versions:set -DnewVersion=1.3-SNAPSHOT -DgenerateBackupPoms=false
    git commit -am "Bump to next development version"
    git checkout master
    git merge release
    git push origin master
    git push origin rel/commons-foo-1.2
    

Make sure, that your release tags follows the naming conventions of the component.

5 Test Main Site Downloads

Wait until the release files are available from the main Apache web site (https://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 https://commons.apache.org/proper/foo.
3. If the component publishes maven artifacts, these artifacts have been replicated to the central maven repo at repo.maven.apache.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 repo 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

• Edit the file https://svn.apache.org/repos/asf/commons/cms-site/trunk/conf/component_releases.properties to hold the current version and release date for your compontent. This can be done using the CMS.
• Stage and publish the main website using the CMS.

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 https://www.apache.org/dist directory is regularly copied to https://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. To prevent a slurry of emails in closing the Jira issues, do the following:
  • Log in to Jira.
  • Click your cursor in the search field and press enter which brings you to search.
  • Ensure that you click the "advanced" search option.
  • In the search field enter project={component_name (e.g. lang)} AND status=resolved, replacing what we have in the curly braces with the appropriate component name.
  • Now, select "Tools" in the top right and choose "Bulk Change" for all of your relevent issues.
  • At step 1, select the issues you wish to transition.
  • At step 2, select "Transition Issues."
  • At step 3, choose close issues.
  • At step 4, enter proper comment, and deselect "Send mail for this update."
  • Click go.
• Update DOAP file Update the component's DOAP file and add a new entry with details of the released version (the DOAP files are located at https://svn.apache.org/repos/asf/commons/cms-site/trunk/doap):

        <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.
• Add release to reporter tool In order to support the PMC in creating reports, the release needs to be added to https://reporter.apache.org/addrelease.html?commons