DRAFT Procedure for creating a release using M2

This is currently a discussion page, and is not (yet) policy

Maven2 Release Procedure

As discussed here: http://markmail.org/message/3emjaadwpf7cr5q3

The Commons Parent POM (v10 onwards) defines repositories such that when using the rc profile, uploaded artifacts go to:

A. Infrastructure Setup (one time)

A.1 Get Familiar with Maven

Reading the Maven documentation is a good start - Releasing A Maven Project.

A.2 Signature Keys

You need to sign the released artifact using your PGP key which implies

See also:

A.3 Maven Installation

After having a lot of problems (Oct. 2009) the following configuration is known to work

However, on Un*x, you may encounter http://jira.codehaus.org/browse/MSITE-404 which will at least prevent staging a site. On Mac, you may also encounter http://jira.codehaus.org/browse/MRELEASE-424 for which there is a workaround.

A.4 Maven Server Settings

It is a good idea to check your settings.xml that it contains the corresponding server entries for the repositories and websites defined in the commons parent pom. If you have a different user name on your box than on people.apache.org you local user name will be used for authentication. Therefore the authentication will fail and after a few retries your are locked out from people.apache.org for a day - which in turn makes cutting a release rather lengthy. In theory you could also provide your password in the server section below but this unsafe and did not work in my case. 

<servers>
  <server>
    <id>apache.releases</id>
    <username>YOUR_APACHE_USERNAME</username>
    <filePermissions>664</filePermissions>
    <directoryPermissions>775</directoryPermissions>
  </server>
  <server>
    <id>apache.website</id>
    <username>YOUR_APACHE_USERNAME</username>
    <filePermissions>664</filePermissions>
    <directoryPermissions>775</directoryPermissions>
  </server>
  <server>
    <id>apache.snapshots</id>
    <username>YOUR_APACHE_USERNAME</username>
    <filePermissions>664</filePermissions>
    <directoryPermissions>775</directoryPermissions>
  </server>
</servers>

B. Release Preparation

B.1 Check Your Project

Here you find a list of reminders what to double-check before cutting a release candidate

B.2 Prepare Your Version Number

A guideline regarding version numbering can be found at http://commons.apache.org/releases/versioning.html - within Commons we reached the following consensus

B.3 Prepare Your Maven Variables

During the staging process a directory is created on people.apache.org based on the content of the following Maven variables

That could look like the following snippet taken from commons-exec 

<properties>
  <commons.release.version>1.0.0</commons.release.version>
  <commons.rc.version>RC2</commons.rc.version>
</properties>

B.4 Update Your Download Page

The commons-build plugin generates a download page in ./src/site/xdoc/ based on commons.release.version 

mvn commons:download-page

B.3 Define Staging Site for Release Candidate

Also ensure that the rc profile will stage the site (rather than update the Commons component website). See bottom of Commons SCXML POM as an example. See COMMONSSITE-26 for background. 

<profiles>
  <profile>
    <id>rc</id>
    <distributionManagement>
      <!-- Cannot define in parent ATM, see COMMONSSITE-26 -->
      <site>
        <id>apache.website</id>
        <name>Apache Commons Release Candidate Staging Site</name>
        <url>${commons.deployment.protocol}://people.apache.org/www/people.apache.org/builds/commons/${commons.componentid}/${commons.release.version}/${commons.rc.version}/site</url>
      </site>
    </distributionManagement>
  </profile>
</profiles>

B.5 Prepare Your Assembly Descriptors

If you are declaring/using your own assembly descriptors make sure that they are not using ${version} but ${commons.release.version} - there seems to be an odd bug which results in an incorrectly expanded version string, e.g. commons-exec-2.4.1-src. If in doubt look at ./src/assembly/src.xml

B.6 Commit Your Changes

When you followed the instructions you have modified a couple of files by now - commit them now otherwise the release process will fail.

B.7 Dry Run Your Maven Release

Check that your poms will not lose content when they are rewritten during the release process.

C. Run The Release Process

C.1 Stage Artifacts and Site

  1. mvn -Prc release:prepare

  2. mvn -Prc release:perform

C.2 Remove SHA1 and MD5 Fingerprints of PGP Signatures

During the release process some unwanted fingerprints of all ASCII-armored files are generated, e.g. "commons-foo.jar.asc.md5" and "commons-foo.jar.asc.sha1". It is a good idea to remove them manually for the time being.

D. Vote

D.1 Send Out The Vote

Below you find a vote template to save you some time ... 

Tag:

https://svn.apache.org/repos/asf/commons/proper/YOUR_PROJECT/tags/${commons.rc.version}

Site:

http://people.apache.org/builds/commons/YOUR_PROJECT/${commons.release.version}/${commons.rc.version}/site/index.html

Binaries:

http://people.apache.org/builds/commons/YOUR_PROJECT/${commons.release.version}/${commons.rc.version}/staged/commons-exec/commons-exec/${commons.release.version}/

[ ] +1 release it
[ ] +0 go ahead I don't care
[ ] -1 no, do not release it because

D.2 React to the Vote

If vote fails, undo and redo previous steps as appropriate (make sure you use a new tag, e.g. if RC2 fails, then create RC3). And rest assured that most releases need more than one release candidate ... :-)

E. Go live

E.1 Copy to "dist"

We need to copy distribution archives to the Commons dist/ area which is located on people.apache.org under /www/www.apache.org/dist/commons. (This content is also automatically copied to archive.apache.org.) We also need to update the "current" symlinks to point to the current version, using the symlinks.sh tool available in https://svn.apache.org/repos/private/committers/tools/releases/symlinks.sh

Here's an example used for commons-dbutils: 

cd /www/www.apache.org/dist/commons/dbutils/binaries/
cp /www/people.apache.org/builds/commons/dbutils/1.2/RC3/staged/commons-dbutils/commons-dbutils/1.2/*bin* .
cd ../source
cp /www/people.apache.org/builds/commons/dbutils/1.2/RC3/staged/commons-dbutils/commons-dbutils/1.2/*src* .
cd ..
~/svn/apache-committers/tools/releases/symlinks.sh 1.2

E.2 Copy Artifacts from Staging

The Maven Stage plugin copies the artifacts (from your release candidate) to the M2 sync directory (people.apache.org/repo/m2-ibiblio-rsync-repository).

The following example was used to do the copy the artifacts for commonse-exec-1.0 based on RC5 

mvn stage:copy -Dsource="http://people.apache.org/builds/commons/exec/1.0/RC5/staged/" \
  -Dtarget="scp://people.apache.org/www/people.apache.org/repo/m2-ibiblio-rsync-repository" \
  -DtargetRepositoryId=apache.releases \
  -Dversion=1.0

E.3 Deploy the Site

Run mvn site-deploy to deploy the site - please note that you are deploying the site of the next development snapshot.

E.4 Create the SVN Release Tag

If you have used a "RC" tag (e.g. "EXEC_1_0_1_RC5") for the M2 release preparation you need to copy the SVN tag in order to create an official release tag.

The following example was used for creating the release tag on commons-exec-1.0.1 

svn copy https://svn.apache.org/repos/asf/commons/proper/exec/tags/EXEC_1_0_1_RC5 \
  https://svn.apache.org/repos/asf/commons/proper/exec/tags/EXEC_1_0_1 \
  -m "The RC5 passed to vote so this will be the release tag"

F. Celebrate

F.1 Prepare Your Celebration

Make sure a couple of things

F.2 Send an Announcement

Send an announcement to the developer and user mailing list. Since you have dutifully updated your changes.xml you can generate the announcement in ./target/announcement/ 

> mvn changes:announcement-generate

G. Tidy up

G.1 Remove old releases

Once the new release has been available for a few days, any files from previous releases should be deleted from the binaries and source directories.

Releasing commons-parent pom

Procedure for creating a release using M2 (outdated by above)

This assumes that the Commons Proxy is about to vote on 1.0-RC3.

CreatingReleases (last edited 2009-11-20 21:07:14 by DennisLundberg)