Nexus Migration Guide

Contents

Migration
- Staging
First Release
Gotchas !
References

This guide is here for project's release managers. It explains what have 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.

Migration

OW2 has installed a Nexus maven repository manager to provide a better management of the maven development process.

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

As a consequence, OW2 won't maintain the old repository anymore.

Disengagement will be done in 3 phases:

Repository will be read only
- Projects will no more be able to deploy artifacts to release and snapshot repository
Repository content will be transfered into Nexus
- Dedicated hosted repositories will be created for each old repository
- URL redirection will be setup so that old URLs will be redirected to new nexus hosted repositories
Repository will be deleted
- Soon after repository transfert, as nobody will be able to access the old content, we will be able to safely delete that content (hosted repositories in nexus still being available)

Read-only mode for repositories will be performed at the end of October (in 3 monthes at the date of writing).

The migration of projects starts right now (Nexus being already fully functional) !
Release managers must open a JIRA Task (not issue or new feature) on the OW2 Service Desk project (component OW2 Nexus) to setup the appropriate permissions before trying to release.
They have to provide the name of the project for which they apply for and a mailing list where notifications emails will be sent.

The no-reply@ow2.org address has to have the right to post mails on this list.

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.

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 applies 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 gone 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 synched 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 releases 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 applies 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>

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 do not apply to snapshot repositories, but as everyone know, 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 happen, 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 an module that have your project's groupId (org.ow2.something), so that it will be synched 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>