Testing Maven Release Plugin Auto-Increment Version Number

Abstract

The Maven release plugin is a very powerful tool and I rely on it heavily for coordinating software releases. Typically, software release version numbers follow a simple 1.0.0.0-SNAPSHOT format. But recently I had need to add a qualifier to the version number - something like 1.0-beta-SNAPSHOT or 1.0.0-fix-bug-description-SNAPSHOT. After my 1st attempt to add the qualifier, the Maven release plugin auto-incremented the version number in an unexpected way. Therefore, I needed to research the Maven release plugin version auto-increment behavior but do so without making a bunch of nonsense tags in the production Git repository (I didn’t have a dev repository to work with). The purpose of this blog is to show how the Maven release plugin can be configured so it can run locally and not make changes to production source control.

Disclaimer

This post is solely informative. Critically think before using any information presented. Learn from it but ultimately make your own decisions at your own risk.

Requirements

I did all of the work for this post using the following major technologies. You may be able to do the same thing with different technologies or versions, but no guarantees.

• NetBeans 11.2
• Maven 3.3.9 (Bundled with NetBeans)
• maven-release-plugin 2.5.1
• Java 11 (zulu11.35.15-ca-jdk11.0.5-win_x64)
• Git for Windows 2.25.0

NOTE The Maven release plugin assumes executables (like git) are on the PATH. If you get an error that the git command is not found, you need to make sure Git is installed independent of your IDE and on the PATH.

Download

Visit my GitHub page https://github.com/mjremijan to see all of my open source projects. The code for this post is located at: https://github.com/mjremijan/thoth-maven-release-plugin

Install Git

The 1st thing you’ll need to do is install Git. Even if Git is integrated into your IDE (like with NetBeans), the Maven release plugin assumes the executables it needs are available on the PATH. Download, install, and configure PATH for your environment.

POM <scm> Tag

The 2nd thing you’ll need to do is configure the POM <scm> tag. When the Maven release plugin runs, it uses the <scm> tag values to identify the location of the source control system.

The relevant configuration is below, see the full pom.xml on GitHub.

Because I want to run locally and not connect to a production source control system, my example uses Git. Git runs very nicely without needing a server. Let’s take a look at the <scm> tag.

Listing 1 - <scm> tag

<scm>
  <url>scm:git:file://D:/Projects/thoth-maven-release-plugin/.git</url>
  <connection>
    scm:git:file://D:/Projects/thoth-maven-release-plugin/.git</connection>
  <developerConnection>
    scm:git:file://D:/Projects/thoth-maven-release-plugin/.git
  </developerConnection>
</scm>

The code in Listing 1 shows my configuration for the <scm> tag. Obviously, the reference to the project’s .git folder on the file system of my computer should stand out to you. You must change this value for your computer. Remember, the goal is to work locally! This configuration gets you there.

After configuring the <scm> tag, the next thing to do is configure the maven-release-plugin. Let’s look at that next.

POM maven-relase-plugin

The 3rd thing to do is configure the maven-release-plugin artifact. This configuration is for the Maven staging repository.

The relevant configuration is below, see the full pom.xml on GitHub. Let’s take a look at this configuration.

Listing 2 - maven-release-plugin tag

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-release-plugin</artifactId>
      <version>2.5.1</version>
      <dependencies>
        <dependency>
          <groupId>org.apache.maven.shared</groupId>
          <artifactId>maven-invoker</artifactId>
          <version>2.2</version>
        </dependency>
      </dependencies>
      <configuration>
        <stagingRepository>
          localforme::default::file://C:/Users/Michael/.m2/repository
        </stagingRepository>
      </configuration>
    </plugin>
    ....
</build>

Line 6 sets the maven-release-plugin to version 2.5.1. This was current at the time of my research (2019 Q2). Using a version below 2.5.2 has some additional gotchas which I’ll get to next.

Line 8 sets the maven-invoker dependency to version 2.2. Maven 3.3 changed the script name (on Windows) from mvn.bat to mvn.cmd. The maven-release-plugin below version 2.5.2 assumes mvn.bat. Changing maven-invoker to version 2.2 changes the assumption to mvn.cmd so Maven 3.3+ can be used (Lucas, 2015). If you use maven-release-plugin greater than or equal to version 2.5.2, you don’t need this maven-invoker configuration.

Line 15 sets the location of the Maven staging repository. Typically you would have this set in settings.xml. If it’s not set, you’ll get build errors. I show how to configure it here. If you have it in settings.xml you can remove this configuration.

Now that the pom.xml is configured, let’s look next at how to run this.

MVN Command

With the configuration now set, it’s time to run the Maven project and test that everything is working. Listing 3 shows the properties and switches for mvn.

Listing 3 - mvn command

mvn
  -Dmaven.test.skip=true
  -Dmaven.javadoc.failOnError=false
  --batch-mode release:clean release:prepare release:stage

There is not much to this command line. Line 4 is the most important. It specifies the maven-release-plugin goals to execute.

Now you are ready for testing. Run the command and see what happens.

Summary

If you are using an IDE like NetBeans which automatically watches and reloads files when changes are detected on the file system, you can open the pom.xml, then run the mvn command, and finally watch the <version> tag automatically change as Maven is running. This way you can start with whatever value you want for the <version> tag and research how it automatically gets changed. Enjoy!

References

Lucas. (2015, July 1). Failed to execute goal maven preprepared [Web log comment]. Stackoverflow. Retrieved from https://stackoverflow.com/questions/29755620/failed-to-execute-goal-maven-releaseprepare.