Nexus / Maven Release Guide

Contents

OW2 Nexus maven repository
- Staging
First Release
Gotchas !
References

This guide is here for project's release managers. It explains what has to be done in order to properly perform a release on the OW2 Nexus instance.
Nexus administrators should read the admin guide to setup Nexus for a new project.

OW2 Nexus maven repository

OW2 has installed a Nexus maven repository manager to provide a better management of the maven development process (the old repository, maven.ow2.org, has been discontinued).

You can browse it here : http://repository.ow2.org/nexus/
It offers advanced repository hosting capabilities such as staging, releases validation before central synchronization, ...
You can read more on Sonatype's web site: http://nexus.sonatype.org

Releases managers also have to read this guide before their first release.

Staging

Staging is a mechanism provided by Nexus helping to manage quality of the releases.
Once the release has been performed (using the maven release plugin), the artifacts are still not publicly available in the release repository.
A temporary repository (containing only the artifacts of the release) is managed by Nexus.

Staging (repo creation + deployment) is managed by the maven-release-plugin (more advanced functions can be delegated to Sonatype's nexus-staging-maven-plugin), during the deploy phase (mvn release:perform): see below, "Release process" chapter.

When all the artifacts are in this staging repository, it has to be manually closed (using nexus web interface).
Once closed, you cannot add artifacts anymore. But there is more: when closing, a set of rules is applied to the artifacts to check their conformance (see below).

If the rules apply cleanly (without errors), then the staging repository can be released (using nexus web interface).
At this moment, the team can check the release. If they think something went wrong, the staging repository can be deleted and a new staging process can begin again.

Once the staging repository has been released, artifacts flow to the release repository and are then synced into central.

First Release

Before performing the first project's release on Nexus, a couple of changes need to be done.

Versions

Maven

Releases Managers can only release using a Maven v2.2.x or Maven 3.x (due to some GPG signatures issues).

Plugins

Maven 3 considers that plugins declared without a fixed version are threatening the stability of the build.
It is therefore a good move to manage the project's plugins versions.

Changing Parent's POM

Any released module must inherit (directly or indirectly) from the OW2 organizational POM (GAV : org.ow:ow2).

At the time of writing, the latest version of this POM is 1.5.

GPG Key

All released artifacts must be signed with a GPG key.

Release Managers must read the Maven/GPG documentation. They should not forget to distribute their public key to key servers.

Add your GPG passphrase in your $HOME/.m2/settings.xml if you don't want to type it again and again during releases:

Repositories

Release and Snapshot repositories are write protected for artifacts deployment.
Release Managers (or anyone who do a deploy) have to declare their credentials for the OW2 repositories in their $HOME/.m2/settings.xml:

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                              http://maven.apache.org/xsd/settings-1.0.0.xsd">

  <servers>

      <server>
          <id>ow2.release</id>
          <username>[Your OW2 Forge username here]</username>
          <password>[Your OW2 Forge password here]</password>
      </server>
      <server>
          <id>ow2.snapshot</id>
          <username>[Your OW2 Forge username here]</username>
          <password>[Your OW2 Forge password here]</password>
      </server>

  </servers>

</settings>

POM Rules

Theses rules apply to the parent POM of the staged artifacts (for a multi-module project).

General

Project POM must have the following elements:

<modelVersion>
<groupId>
<artifactId>
<version>
<packaging>
<name>
<description>
<url>
<licenses>
<scm><url>
<scm><connection>
<developers>

Release process

To prepare the release

mvn release:prepare -Dresume=false

To release in case of success

mvn release:perform

This phase should compile, package, add javadoc and source archives, and sign everything, so that the whole stuff be ready for maven central deployment.

Information is required in the pom.xml, to tell the maven-release-plugin where the Nexus staging repository is:

  <distributionManagement>
   <repository>
      <id>ow2.release</id>
      <url>https://repository.ow2.org/nexus/service/local/staging/deploy/maven2/</url>
   </repository>
  </distributionManagement>

Note: the staging repository will be automatically created if not present. When done, it should be visible in the Nexus web UI.

To rollback in case of failure

mvn release:rollback

Then, when necessary (frequently when the rollback comes after the release:perform phase), manually remove tag on Git repo:

git tag -d [tag-name]
git push origin :refs/tags/[tag-name]

No Releases Repositories

This rule is currently not applied yet for central synchronization (but might be in the future).
As a consequence, the OW2 Nexus repository will also not apply this rule.

But it is a good idea to start thinking about this problem right now

The set of rules deployed on Nexus states that no release repository other than central should be declared in the POMs.
This is because central has to be self-contained.

This rule does not apply to snapshot repositories, but as everyone knows, a released project shouldn't (and cannot) depends on not released artifacts.

This is a very important point and is the one that could make the migration difficult, since all project's dependencies may not be in central.
If this happens, you have a couple of choices:

Update your dependencies to rely only on the ones deployed on central (may or may not be possible)
Follow the 3rd party uploading guide from Sonatype
Repack the dependencies within modules that have your project's groupId (org.ow2.something), so that it will be synced on central.

Readings:

Tips

wagon-ssh in build/extensions is not required anymore (except for thoses producing a maven site with scp).
Use the ow2-release release profile if you want to add specific release behavior
Update your /.m2/settings.xml to use <password> instead of (or in addition to) <privateKey> for the ow2.releases and ow2.snapshots servers.

Gotchas !

Because of the bug MRELEASE-459 of the maven-release-plugin, the <releaseProfiles>ow2-release<releaseProfiles> plugin configuration's element is not honored if your maven's release environment has no active profile when the release is performed. That leads to missing artifacts (like javadocs and sources artifacts) in the staging repository.

Until the staging repository is closed, it's always possible to change the content of the staging repository (altering files, removing, adding stuff). So it's perfectly OK to workaround that issue (after mvn release:perform) by doing a mvn -Pow2-release deploy in the target/checkout directory.

The other way to prevent that issue to happen is to have an empty <profile> definition in your .m2/settings.xml that is always active.

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                             http://maven.apache.org/xsd/settings-1.0.0.xsd">

<profiles>

   
   <profile>
     <id>empty</id>
     <activation>
       
       <activeByDefault>true</activeByDefault>
     </activation>
   </profile>

</profiles>

</settings>