Releasing A Maven Project

What follows is a description of releasing a Maven project to a staging repository, whereupon it is scruntized by the community, approved, and transfered to a production repository.

Prerequisite

Be sure that:

  • you have all Maven servers defined in your settings.xml. For more information, please refer to Committer settings .
  • you have created your GPG keys. For more information, please refer to Making GPG Keys .

In order to release a project you must also have the following setup in your $HOME/.m2/settings.xml which is a profile that defines the staging repository.

Here's what your release profile might look like in your $HOME/.m2/settings.xml :

<settings>
  ...
  <profiles>
    <profile>
      <id>release</id>
      <properties>
        <gpg.passphrase>secretPhrase</gpg.passphrase>
        <deploy.altRepository>apache.releases::default::scp://hostname/path/to/directory/stage/repo</deploy.altRepository>
      </properties>
    </profile>
  </profiles>
  ...
</settings>

Everything that you need to release has been configured in the POM all Maven projects inherit from. The release plugin configuration being used is the following:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-release-plugin</artifactId>
  <version>2.0-beta-7</version>
  <configuration>
    <!-- This element will be overriden by children -->
    <tagBase>https://svn.apache.org/repos/asf/maven/pom/tags</tagBase>
    <useReleaseProfile>false</useReleaseProfile>
    <goals>deploy</goals>
    <arguments>-Prelease</arguments>
  </configuration>
</plugin>

And the profile being used for releases is the following:

<profile>
  <id>release</id>
  <build>
    <plugins>
      <!-- We want to sign the artifact, the POM, and all attached artifacts -->
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-gpg-plugin</artifactId>
        <configuration>
          <passphrase>${gpg.passphrase}</passphrase>
        </configuration>
        <executions>
          <execution>
            <goals>
              <goal>sign</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
      <!-- We want to deploy the artifact to a staging location for perusal -->
      <plugin>
        <inherited>true</inherited>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-deploy-plugin</artifactId>
        <configuration>
          <altDeploymentRepository>${deploy.altRepository}</altDeploymentRepository>
          <updateReleaseInfo>true</updateReleaseInfo>
        </configuration>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-source-plugin</artifactId>
        <executions>
          <execution>
            <id>attach-sources</id>
            <goals>
              <goal>jar</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <executions>
          <execution>
            <id>attach-javadocs</id>
            <goals>
              <goal>jar</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</profile>

Release Process for Part Of Maven

  1. Prepare your poms for release:
    1. Make sure there are NO snapshots in the poms to be released.
    2. Check that your poms will not lose content when they are rewritten during the release process.
      • mvn release:prepare -DdryRun=true
      • Diff the original file pom.xml with the one called pom.xml.tag to see if the license or any other info has been removed. This has been known to happen if the starting <project> tag is not on a single line. The only things that should be different between these files are the <version> and <scm> elements. Any other changes, you must backport yourself to the original pom.xml file and commit before proceeding with the release.
      • Remember to do 'mvn release:clean ' before you start the real release process.
      • Verify that all pom.xml have a SCM definition.
  2. Publish a snapshot:
    >mvn deploy
...
[INFO] [deploy:deploy]
[INFO] Retrieving previous build number from apache.snapshots
...

    IMPORTANT NOTE : Be sure that the generated artifacts respect the Apache release rules : NOTICE and LICENSE files should be present in the META-INF directory within the jar. For -sources artifacts, be sure that your pom does NOT use the maven-source-plugin:2.0.3 which is broken. The recommended version at this time is 2.0.4.

    Note : You could verify the deployment under Maven Snapshot repository on Apache.

    http://people.apache.org/repo/m2-snapshot-repository/org/apache/maven/plugins/maven-XXX-plugin/Y.Z-SNAPSHOT/
  3. Run fix-permissions.sh

    Login to people.apache.org, then run:

    /www/people.apache.org/repo/m2-snapshot-repository/fix-permissions.sh

    This will set maven-metadata.xml file permissions back to 664, and set permissions on any directories you created to 775.

  4. Prepare the release
    mvn release:prepare

    Note : Preparing the release will create the new tag in SVN, automatically checking in on your behalf.

  5. Stage the release for a vote
    mvn release:perform
  6. Stage the latest documentation

    The plugin parent pom is configured to stage the documentation in a "versioned" directory such as /plugins/maven-XXX-plugin-Y.Z-SNAPSHOT .

    IMPORTANT NOTE : You need to stage the documentation for the current release version.

    cd target/checkout

    mvn site:stage-deploy -Preporting

    Note : You could verify the deployment of the site on the Maven website (you need to wait the sync).

    http://maven.apache.org/plugins/maven-XXX-plugin-Y.Z/

    Some developers have reported problems with the stage-deploy goal. In that case, you can stage the site locally and upload it manually:

    mvn site:stage -Preporting
scp -r target/staging/people.apache.org/www/maven.apache.org/plugins/maven-XXX-plugin YOUR_APACHE_USERNAME@people.apache.org:/www/maven.apache.org/plugins/maven-XXX-plugin-Y.Z
  7. Propose a vote on the dev list with the closed issues, the issues left, the staging repository and the staging site. For instance:
    To: "Maven Developers List" <dev@maven.apache.org>
Subject: [VOTE] Release Maven XXX plugin version Y.Z

Hi,

We solved N issues:
http://jira.codehaus.org/secure/ReleaseNote.jspa?projectId=XXX&styleName=Html&version=XXX

There are still a couple of issues left in JIRA:
http://jira.codehaus.org/secure/IssueNavigator.jspa?reset=true&pid=XXX&status=1

Staging repo:
http://people.apache.org/~YOUR_APACHE_USERNAME/staging-repo/maven-XXX-plugin/

Staging site:
http://maven.apache.org/plugins/maven-XXX-plugin-Y.Z/

Guide to testing staged releases:
http://maven.apache.org/guides/development/guide-testing-releases.html

Vote open for 72 hours.

[ ] +1
[ ] +0
[ ] -1

    Once a vote is successful, post the result to the dev list and cc the pmc.

  8. Copy from the staging repo to the production repo

    Once the release is deemed fit for public consumption it can be transfered to a production repository where it will be available to all users.

    Here is an example on how to use the stage plugin:

    mvn stage:copy -Dsource="http://people.apache.org/~YOUR_USERNAME/staging-repo" \
               -Dtarget="scp://people.apache.org/www/people.apache.org/repo/m2-ibiblio-rsync-repository" \
               -Dversion=Y.Z \
               -DtargetRepositoryId=apache.releases

    Note: The version parameter is currently ignored and the entire staging repository is synced, not just the given version or the current project. It still needs to be provided, though.

    Releasing a Project Directly into a Production Repository

    If you want to release directly to a production repository then you simply configure the staging repository to point at the production repository by using the following in your $HOME/.m2/settings.xml :

    <settings>
  ...
  <profiles>
    <profile>
      <id>release</id>
      <properties>
        <gpg.passphrase>secretPhrase</gpg.passphrase>
        <deploy.altRepository>apache.releases::default::scp://people.apache.org/www/people.apache.org/repo/m2-ibiblio-rsync-repository</deploy.altRepository>
      </properties>
    </profile>
  </profiles>
  ...
</settings>

    This will allow you to bypass the staging phase and push the release directly into a production repository. It is assumed that you have pushed a snapshot somewhere that people have looked at and approved of.

  9. Run fix-permissions.sh again

    Login to people.apache.org, then run:

    /www/people.apache.org/repo/m2-snapshot-repository/fix-permissions.sh

    This will once again set maven-metadata.xml file permissions back to 664, and set permissions on any directories you created to 775. The script lives in m2-snapshot-repository, but it's smart enough to fix permissions in m2-ibiblio-rsync-repository and m2-incubating-repository also.

  10. Deploy the current website

    Note: Be sure to generate and deploy the site using the same version of the release. Typically, you need to check out the tag (or go to target/checkout )

    mvn site-deploy -Preporting
  11. Review Website

    Wait for the files to arrive at

    http://maven.apache.org/plugins/maven-XXX-plugin
  12. Update the plugins page

    If this is a plugin release, update the version number for the plugin on the /plugins/index.html page.

  13. Update JIRA

    Go to Admin section in JIRA for the maven-XXX-plugin project and mark the Y.Z version as released. Create version Y.Z+1, if that hasn't already been done.

  14. Create an Announcement. For instance:
    From: YOUR_APACHE_EMAIL
To: announce@maven.apache.org, users@maven.apache.org
Cc: dev@maven.apache.org
Subject: [ANN] Maven XXX Plugin Y.Z Released

The Maven team is pleased to announce the release of the Maven XXX Plugin, version Y.Z

This plugin (insert short description of the plugin's purpose).

http://maven.apache.org/plugins/maven-XXX-plugin/

You can run mvn -up to get the latest version of the plugin, or specify
the version in your project's plugin configuration:

<plugin>
 <groupId>org.apache.maven.plugins</groupId>
 <artifactId>maven-XXX-plugin</artifactId>
 <version>Y.Z</version>
</plugin>

Release Notes - Maven 2.x XXX Plugin - Version Y.Z

(Copy Here Release Notes in Text Format from Jira)

Enjoy,

-The Maven team
  15. Add the release to the next board report, in the private subversion area.
  16. Add the release to the wiki, under the Recent Releases section of the front page and on the Releases page.
  17. Celebrate :o)