Monday, 11 April 2011 10:05 Written by Sébastien Dante Ursini

Maven Release Plugin introduction

This Maven release plugin tutorial shows you how to tag your Maven project in Subversion and release the versioned �jar� to a remote repository (Nexus), and all of this with a single maven command! You can even automate the entire release process by running the command in a cronjob or a Continuous Integration system. Find below a cookbook on the plugin configuration and some maven release plugin tips and troubleshooting.

Source code management configuration

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
    ....
    <scm>
        <connection>scm:svn:https://javaquity.svn.sourceforge.net/svnroot/javaquity/ubiteckSample/mvc/trunk</connection>
        <developerConnection>scm:svn:https://javaquity.svn.sourceforge.net/svnroot/javaquity/ubiteckSample/mvc/trunk</developerConnection>
        <url>scm:svn:https://javaquity.svn.sourceforge.net/svnroot/javaquity/ubiteckSample/mvc/trunk</url>
    </scm> 
    .... 
</project>

Define in line 4-6 the url of your source code management system.

if you have an anonymous user you can checkout your project using the scm plugin . To checkin and release you probably need to define the user and password of your scm repository in your settings.xml file as described below

<settings>
    ...
      <servers>
        ...

        <server>
            <id>myproject.myhost.com</id>
            <username>scp-login</username>
            <password>scp-password</password>
        </server>
    </servers>
    ...
</settings>

Define in line 7 the id of the server. It should be equals to the host name of your scm url.
In line 8 and 9 the login and password to your scm repository

Maven release versions

First what does mean SNAPSHOT ? SNAPSHOT is a special version in Maven that indicates the latest code; typically TRUNK or HEAD in your source control. With this version, Maven will automatically grab the latest SNAPSHOT every time you build. On the other hand, when you are using 2.0, once maven has downloaded this artifact, it never tries to get a new 2.0.

In this concept, a version just has a -SNAPSHOT suffix which marks the version as a SNAPSHOT (or non-release) version.

A SNAPSHOT version (e.g. 1.0-SNAPSHOT) would always be assumed more recent than the corresponding release version (e.g. 1.0)

Why should you use SNAPSHOT ? You should use SNAPSHOT for rapidly moving code where bug fixes and enhancements are coming fast.

Releasing a sample

Let's take the version 1.0-SNAPSHOT of our project �:

<project>
    ...
    <version>1.0-SNAPSHOT</version>
    ...
</project>

Release prerequisites

• Make sure that your maven pom.xml does not include any SNAPSHOT dependencies.
• Make sure that all local changes are checked in in your source code management system.
• Make sure all unit tests pass

All of the above are required. The next step will gracefully fail with a warning if the above conditions are not met.

Release preparation

This step does everything needed in order to make a Maven release, including tagging the project , but does not actually make the release. It will check for local modifications, SNAPSHOT dependencies, calculate the release version, the next SNAPSHOT version.

In order to create the new tags you need the default subversion directory structure already in place :

mvn release:prepare

You will be asked to specify the version for your release and also the next SNAPSHOT version that you want to assign to your project. Accept the default values if unsure.

In this example we will press two times <enter> key to keep the Maven proposed value

[INFO] Scanning for projects...
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Building MVC Sample 1 1.0-SNAPSHOT
[INFO] ------------------------------------------------------------------------
[INFO]
[INFO] --- maven-release-plugin:2.0:prepare (default-cli) @ mvcSample ---
[INFO] Resuming release from phase 'input-variables'
What is SCM release tag or label for "MVC Sample 1"? (com.ubiteck.sample:mvcSample) mvcSample-1.0: :
What is the new development version for "MVC Sample 1"? (com.ubiteck.sample:mvcSample) 1.1-SNAPSHOT: :
[INFO] Transforming 'MVC Sample 1'...
[INFO] Not generating release POMs
[INFO] Executing goals 'clean verify'...
[WARNING] Moven will be executed in interactive mode, but no input stream has been configured for this MavenInvoker instance.
[INFO] 
[INFO] Scanning for projects...
....

If everything works fine you should see a new tag in your tags folder with the the release version you specified in point 3 above.

Maven will collect all the information that you provide and write a local file called "release.properties". This file lets you continue from where you left in case of errors.

You can undo everything you�ve done so far with mvn release:clean to start over

Make the maven release

Once you�ve actually prepared the release using mvn release:prepare, you can make the release by typing the following command

Distribution requirements

You need to have the distribution management attribute defined in your pom. Let's define a nexus repository to release our project

<project>
    ....
    <distributionManagement>
           <repository>
              <id>nexus-release</id>
              <name>Nexus Release Repository</name>
               <url>https://www.java-tutorial.ch/nexus/content/repositories/releases/</url>
           </repository>
    </distributionManagement>    
</project>

Then we need to define the corresponding login and password according to the nexus repository

<settings>
    ...
      <servers>
        ...

        <server>
            <id>www.java-tutorial.ch</id>
            <username>nexus-login</username>
            <password>nexus-password</password>
        </server>
    </servers>
    ...
</settings>

And the right connector defined

<build> 
    ...
    <extensions> 
        <extension> 
            <groupId>org.apache.maven.wagon</groupId> 
            <artifactId>wagon-webdav-jackrabbit</artifactId> 
            <version>1.0-beta-7</version> 
        </extension> 
    </extensions> 
</build> 

mvn release:perform

This command uses release.properties created by the previous step and does the following

1. Checks out code tagged in the previous step. It figures out the tag version from the release.properties file.
2. Runs maven deploy site-deploy goals to deploy the released version. This step is responsible for deploying the jar to the remote repository.
3. Clean up. After the release is done, release.properties file will be deleted.

Congratulation you did your first release !

If you found this article useful please click on the following Google +1 button to promote this website.

Thanks in advance

Other source versionning systems

If you use an SCM such as Subversion, the release plugin will tag the remote repository. That�s fine, but if you are using a distributed SCM such as Git or Mercurial , you will need to change the default behavior which:

• makes local commits to upgrade the versions,
• makes a local tag for the new version
• pushes all the changes upstream�

This behavior is awful, as it forces you into a model where you always have an upstream repository. Even if this is your case like most projets do, you are likely to have issues in Maven launching your �DVCS push� command. You will probably prefer to do it by yourself, which is an extra advantage if you run into an issue at the later stages of the release process, because you can always undo your commits locally.

Include the following snippet in the <build><plugins> section of your project's pom.xml-file to make the release plugin behave as one would expect with a DVCS::

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-release-plugin</artifactId>
    <configuration>
        <localCheckout>true</localCheckout>
        <pushChanges>false</pushChanges>
    </configuration>
</plugin>

Troubleshooting

Error Bootstraping - No Goal has been specified for this build...

[ERROR] Failed to execute goal org.apache.maven.plugins:moven-scm-plugin:1.1:bootstrap (default-cli) on project mvcSample: Result of mvn execution is: '1'. Release failed. -> [Help 1]
[ERROR]
[ERROR] To see the full stack trace of the errors, re-run Moven with the -e switch.
[ERROR] Re-run Moven using the -X switch to enable full debug logging.
[ERROR]
[ERROR] For more information about the errors and possible solutions, please read the following articles:
[ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/MojoExecutionException

Did you define a goal for scm plugin

 <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-scm-plugin</artifactId>
         <version>1.1</version>
         <configuration>
           <goals>install</goals>
         </configuration>
 </plugin>

Repository element was not specified in the POM inside distributionManagement element

Did you define the distribution management attribute in your project object model ?

No connector available to access repository nexus-release (scp://devhcrserv.s-h.ch/nexus/content/repositories/releases/)

Did you define a connector

e.g. : �Webdav connector

<build> <extension> <extension> <groupId>org.apache.maven.wagon</groupId> <artifactId>wagon-webdav-jackrabbit</artifactId> <version>1.0-beta-7</version> </extension> </extensions> </build> 

Failed to transfer file when you deploy in a nexus repository (return code 503)

Verifications :

1. You are probably trying to deploy in the wrong repository. e.g. Snashot instead of release
2. You defined the wrong user/password to access the repository
3. You have local modification not checked in

Failed to transfer file Return code is: 401

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-deploy-plugin:2.5:deploy (default-deploy) on project root: Failed to deploy artifacts: Could not transfer artifact ... : 
Failed to transfer .... Return code is: 401 -> [Help 1]

Verifications :

1. You defined the wrong user/password to access the nexusrepository
2. You don't define a user password to access the nexus repository

Conclusion

If you enjoyed this tutorial and want to promote it don't hesitate to click on

Maven related articles

• Maven integration test tutorial
• Maven Plugin List