Maven2 Release Procedure

The Fulcrum Parent POM defines different profiles

The 'rc' profile copies the artifacts to

people.apache.org/www/turbine.apache.org/builds/turbine/fulcrum/${fulcrum.componentid}/${fulcrum.release.version}/${fulcrum.rc.version}/staged

whereas the 'release' profile copies the artifacts to

people.apache.org/www/people.apache.org/repo/m2-ibiblio-rsync-repository

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

A.3 Maven Installation

Currently Maven 2.0.10 or better is required to run the release process

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 fulcrum 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 http://commons.apache.org/releases/versioning.html.

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 yaafi-crypto

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

B.3 Define Staging Site for Release Candidate

Also ensure that the rc profile will stage the site (rather than update the Fulcrum component website).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>Fulcrum Release Candidate Staging Site</name>
        <url>${fulcrum.deployment.protocol}://people.apache.org/www/turbine.apache.org/fulcrum/fulcrum-yaafi-crypto</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 ${fulcrum.release.version} - there seems to be an odd bug which results in an incorrectly expanded version string, e.g. fulcrum-yaafi-crypto-2.4.1-src. If in doubt look at ./src/assembly/src.xml.

B.6 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

In Commons land there are currently the following conventions

C.1 Stage Artifacts and Site

  1. mvn -Prc release:prepare

  2. mvn -Prc release:perform

When the release plugin prompts for the tag name, choose the final name (for example, FULCRUM_YAAFI_CRYPTO_1_0_6).

You may experience memory problems with newer Maven versions. If that happens, set the environment variable

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. "fulcrum-yaafi-crypto.jar.asc.md5" and "fulcrum-yaafi-crypto.jar.asc.sha1". It is a good idea to remove them manually for the time being.

C.3 Fix permissions

For some reason, the site deployed to the staging location will only have group write permissions on the lowest directory level. So it might be necessary to fix the group permissions on you newly created site tree so that others will be able to add new versions later. So like e.g.

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/turbine/fulcrum/tags/${TAG}/

Site:

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

Binaries:

http://turbine.apache.org/builds/turbine/fulcrum/${project.artifactId}/${fulcrum.release.version}/${fulcrum.rc.version}/staged/${project.groupId}/${project.artificatId}/${fulcrum.release.version}/

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

D.2 React on the Vote

If vote fails, undo and redo previous steps as appropriate (make sure SVN tag is deleted before recreating). And rest assured that most releases need more than one release candidate ... :-)

E. Go live

E.1 Copy to "dist"

Copy distributions to http://www.apache.org/dist/ area which is located on people.apache.org under /www/www.apache.org/dist/turbine/fulcrum. The content is also automatically copied to archive.apache.org

E.2 Copy Artifacts from Staging

The Maven Stage plugin copies the artifacts (from you 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 fulcrum-yaafi-crypto-1.0.6 based on RC4

mvn stage:copy \
  -Dsource="http://turbine.apache.org/builds/turbine/fulcrum/fulcrum-yaafi-crypto/1.0.6/RC4/staged" \
  -Dtarget="scp://people.apache.org/www/people.apache.org/repo/m2-ibiblio-rsync-repository" \
  -DtargetRepositoryId=apache.releases \
  -Dversion=1.0.6

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. If you prefer to deploy the actual release site, make sure you keep the directory target/checkout and do the deployment from there.

F. Celebrate

F.1 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/. Like in the case of the site deployment, this works best if you keep the checked-out project after completing the release:perform step.

> mvn changes:announcement-generate

Outdated Fulcrum M2 Migration Guidelines

We decided to migrate from M1 to M2 not only because M1 is a bit outdated but also because doing a proper release is much easier using M2.

How To Make a M2 release

FulcrumMaven2Migration (last edited 2009-10-19 18:55:31 by ThomasVandahl)