Releases with Maven

Use maven for releasing a version of your application for production, easier then doing it by hand. Releases also help in keeping a clear distinction between versions.
mvn release:prepare is a bit like a TAG in svn, only it adjusts the pom too.

How-To

This is the short version, see below for explanation, requirements and links to further information.

1. get a new checkout of your project to a temporary directory: svn co <a href="https://svn.func.nl/<someproject>" title="https://svn.func.nl/<someproject>">https://svn.func.nl/<someproject></a> <newdirectory>
2. change to the new directory and prepare for release with a dry-run: mvn -cpu -U release:prepare -DdryRun=true
3. answer the questions about versions maven asks you
4. check the newly generated poms: pom.xml.next and pom.xml.tag
5. If you're happy, run the release: mvn release:prepare -Dresume=false -Dmaven.test.skip=true release:perform

The ultrashort version is:

• mvn release:prepare
• mvn release:perform

Or you could even run prepare with all the default settings, no questions asked with: mvn release:prepare --batch-mode

Explanations

What maven does and what you have to do

A Maven project consists of a pom file which defines a project. One of the aspects of a project is its version. Every release of your project changes the version in the pom file. If your project consists of several pom files it is very difficult and error prone to keep all the version numbers in sync. This is where the maven release plugin comes in. The plugin offers you several commands to update all the versions in your pom files, update them to your svn repository and create a tag for the version. The plugin does the following steps for you (copied from the Maven Release Plugin Homepage):

• Check that there are no uncommitted changes in the sources
• Check that there are no SNAPSHOT dependencies
• Change the version in the poms from x-SNAPSHOT to a new version (you will be prompted for the versions to use)
• Transform the SCM information in the POM to include the final destination of the tag
• Run the project tests against the modified POMs to confirm everything is in working order
• Commit the modified POMs
• Tag the code in the SCM with a version name (this will be prompted for)
• Bump the version in the POMs to a new value y-SNAPSHOT (these values will also be prompted for)
• Commit the modified POMs

For maven release to work you have to specify the scm (Source controle management) type and url in the pom.xml:

   <scm>
      <connection>
         scm:svn:https://svn.func.nl/thme/tesis-ea/tesis-ea-webapp/trunk
      </connection>
   </scm>

and

   <distributionManagement>
      <repository>
         <id>maven.func.nl</id>
         <name>Func. Internal Repository</name>
           <url>scpexe://maven.func.nl/var/sites/nl.func.maven/www/</url>
      </repository>
   </distributionManagement>

The release plugin checks for a few things when you want to release a new version. It checks that there are no changes in the project you want to release. It is wise to export the project you want to release to a separate directory to be sure there are no changes. The release plugin will notify you if any changes exist and will abort the release procedure.

The release plugin also checks you don't have any dependencies with a SNAPSHOT version in your project. All dependencies in your project must be an actual release.

Usage

Step 1

For starters you'll want to do perform the release with the newest versions and if anything goes wrong you don't want it to affect your workspace. This is why the first step is getting a new checkout in a temp directory. Assuming that your project is on svn, as it should be.

Step 2

It is wise you start with a dry run. This creates the pom files as if they were going to be committed to your svn repository. To perform a dry run, enter the directory of the project you want to release and execute the following command: mvn -cpu -U release:prepare -DdryRun=true

Use -cpu and -U to check repositories for new versions of dependencies and plugins.

Step 3 and 4

A series of questions is presented to you on the screen including the name of the new tag and the new version number for the trunk. The former should be your new release number, the latter should reflect the expected next release. I.e. if you expect a minor bugfix-release you'd set trunk to x.y.z-SNAPSHOT, whereas if you expect a new point release you'd use x.y-SNAPSHOT. You are also asked to give the version of any sub-projects. The command creates a release.properties file with all the values needed for the release. It also creates several pom files which you should check:

• pom.xml.next - The pom file for the next version
• pom.xml.tag - The pom file for copy in the Tags directory of your svn repository.

This is done for all the project and all of its sub-projects. The original pom.xml files are left intact since this is a dry run.

Step 5

If all the values in the release.properties file are correct, and all the pom files are correct you can perform the actual release. This is done with the following command:

mvn release:prepare -Dresume=false -Dmaven.test.skip=true release:perform

• This command will not ask you the questions again This command may not ask you the questions again, depending on the -Dresume=false setting. Value false will prompt the questions again. The value true will continue, asuming the values you entered during release=prepare (which are stored in the release.properties file) to be correct. The command above will alter the pom files to the new version, create and commit a tag and commit the new pom files. All with the values you entered. release:prepare does everything short deploying, release:perform does the actual deploy.
• -Dmaven.test.skip=true is useful, since you already ran the tests in the dry run why wait again?

Troubleshooting

Sometimes release:prepare works but surefire reports throw NPE's. This problem has been solved by checking out and deploying the newly created tag:

• mvn release:prepare -Dresume=false
• check out the tag
• mvn deploy

In general, if your release:perform fails after a release:prepare, run mvn release:clean to undo.

Not happy?

If you are not satisfied with the generated pom files or the release.properties file from the dry run you can reset the release. This can be done in two ways:

mvn release:clean release:prepare -DdryRun=true

or

mvn release:prepare -Dresume=false -DdryRun=true

This will start the process again and will ask you to answer the questions again.

See also

http://maven.apache.org/plugins/maven-release-plugin/index.html