Maven based configuration management with automatic build number

9

An important questions in software deployment and testing is “What is the version of the software I am looking at”. It is frustrating for a tester or an end user not knowing if the planned upgrade is performed or not. Having a solid version numbering policy is a solution to overcome these problems.

There are several places where you want to have the version number of your software available:
- visible for the end user on the login screen.
- visible in the software distribution package (war / ear) for the deployment operator.
- visible in configuration files.
- and even visible in the deployed online manual.

The task of proper version numbering can be performed manually. This takes a solid knowledge of all places where this number is used and a good deal of perseverance when performing these repeating actions.
In a project under development, using an agile development method, there will be frequent builds and releases (daily or even hourly). This asks for automated build numbering. When using maven and subversion, this task can be automated with the maven buildnumber plugin.

Maven buildnumber plugin

June this year I found the maven buildnumber plugin on the internet. This plugin was first only hosted at the University of Calgary. Since this week the buildnumber plugin (http://mojo.codehaus.org/buildnumber-maven-plugin/index.html) is available in the Central maven repository http://repo1.maven.org/maven2/.

Configuring the Maven Buildnumber Plugin

When using the Maven Buildnumber Plugin you have to add the following lines to the master pom.xml. The phase configuration will make sure the builnumber is determined at the very start of the maven build cycle.

<build>
<……>
<plugins>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>buildnumber-maven-plugin</artifactId>
<executions>
<execution>
<phase>validate</phase>
<goals>
<goal>create</goal>
</goals>
</execution>
</executions>
<configuration>
<doCheck>true</doCheck>
<doUpdate>true</doUpdate>
</configuration>
</plugin>
</plugins>
<…..>
</build>

See the Mojo sites for advanced configuration. http://mojo.codehaus.org/buildnumber-maven-plugin/create-mojo.html

Formatting

You can use the following options for build numbering configuration:
Default:

The default configuration (as above) will use the revision number form your SCM system.
This will produce in case of subversuion e.g. buildnumber: 1533

Timestamp:

<configuration>
<format>{0,date,yyyy-MM-dd HH:mm:ss}</format>
<items>
<item>timestamp</item>
</items>
</configuration>

This will produce e.g buildnumber: 2007-11-06 2:32:35


Custom number, combined with text:

<configuration>
<format>Build {0,time} on {0,date} on {1} server.</format>
<items>
<item>timestamp</item>
<item>Autmatic build</item>
</items>
</configuration>

This will produce e.g buildnumber: Build 12:32 PM on Nov 6 on Autmatic build server.

Using the buildnumber plugin in your project.

Naming the produced artefacts with the buildnumber.

When you create the final name of the artefact (the EAR or WAR file) dynamically you can use the buildnumer to distinguish different versions of this artefact.

<build>
<finalName>${project.artifactId}-${project.version}-r${buildNumber}</finalName>
< €¦..>
</build>

This will result in an artefact in the target folder with the buildnumber in the name. E.g.
weblv-ap-1.0-SNAPSHOT-r14-11-2007-09.47.34.war

Resources file

The same buildnumber can be used in your resources file (e.g. an i18n resource file)`

Use the property

login.version=Versie: ${project.version}- build date ${buildNumber}

After processing resources (mvn process-resources) the login.version in the target folder will state:

login.version=Versie: 1.0-SNAPSHOT-  build date 14-11-2007 09.47.34

This property can be used on the login page (see image). This will show to all users when the current version is build.

Conclusion

This easy to use simple plugin is a step forward in Maven based software automation. This feature adds values to your project, especially for configuration managers, testers and key users. Not only during development but also in maintenance mode this plugin is very helpful.

Share.

About Author

Robbrecht is a development manager at AMIS Services. He is Agile coach and Certified Agile Master. He has 10+ years of experience in managing projects with Scrum (first with DSDM). Robbrecht is a strong proponent of the agile principles. With AMIS Robbrecht is responsible for implementing the AMIS Software factory based upon Hudson, Maven, Jira and Subversion and implementing Agile as default method for AMIS projects.

9 Comments

  1. This is all well and good, but I can’t for the life of me get Maven to deploy the artifact to the snapshots repo with any other name than the default, timestamp-based name.
    Any tips on how to do this?

  2. Great!
    Thanks a lot, it worked at first glance!!
    Just a remark: using freemarker, I have a lot of ${…} in my template files.. so, if I need to do some replacements, I need to put my ${buildNumber} at the beginning of the file; otherwise, at first $ token, maven tries to replace and fails, so skip the rest of the file.
    Best would be to use @..@ as separator.
    Anyway, good tutorial!

  3. Thanks for this very nice and helpfull tutorial!

    I managed to add the plugin to my project, but I have a problem with displaying the revision number from my svn repository together with the date of the last (local) build. When I use the default configuration, [buildNumber] indeed points to the right revision number, but when I configure the plugin by myself, it is being replaced by the number of local builds. It looks like I need to point somewhere that I want the revision number retrieved by scm…

    My pom.xml:

    scm:svn:https://xxx/svn/zdip/dev/web/branches/3.0/
    scm:svn:https://xxx/svn/zdip/dev/web/branches/3.0/

    Plugin config:

    false
    true
    Rev: {1,number} Build date: {0,date,dd-MM-yyyy HH:mm:ss}

    timestamp
    buildNumber

    Any ideas would be appreciated.
    Regards,
    Lui Gie

  4. Robbrecht van Amerongen on

    Peter,

    I should not include the buildnumber in your project version. This number is set when releasing the project (with e.g .maven release plugin).
    I would advise you to include the buildnumber somewhere visible in your application (name of the artifact (war/ear) and visible on the login screen. This is especially helpful when you are working with frequent releases of snapshot versions. Using this number always provides you (and e.g. your testers) with information about the version of the application they are looking at.

    When you get “${buildNumber}” instead of a buildnumber it is possible that you forgot to link the buildnumber plugin to a project pahse. See the first block of code where it states “validate“.

    Robbrecht

  5. Thanks, That’s a good example. I’d like to have this set the project version so the deployed POM and artifact name have my chosen format of date or an svn revision. The packaged artifact looks good, but when its installed into my local repository the buildNumber isn’t resolved and I get “${buildNumber}” instead of 456.

    Is it possible or wise to have the buildNumber included in the project version? Or should those be separate for a reason?

    Thanks again.