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.
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?
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!
You also can use the timestamp plugin. Combined with the buildnumber pluigin you can generate these two values.
http://code.google.com/p/maven-timestamp-plugin/
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
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
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.
Yes indeed, my personal site (http://www.hendrikse.name/) as well as my corporate site (http://www.it-essence.nl/) are built with Maven. This has the advantage of having multi-language support, having your sources in CVS and last but not least, continuous integration: at most ten minutes after committing a modification to my site, it is automatically deployed on the server!
Hi Zeger, thanks for your reaction!.
I have looked at your site. Am I right you have created your personal site (http://www.hendrikse.name/) with maven to? Nice work!
Very interesting indeed. It does precisely what I did with Ant scripts (see Having a time stamp of your Maven build available in your web application on my own technical blog) and even more. From now on I can use the version numbers in a standard way. Thanks for this clear explanation!