Fork me on GitHub

Version number rules

Introduction

Notice: The limitations explained in this paragraph were true in Maven 2.x, but have been fixed in Maven 3.x (see Maven Versioning Wiki page for more details)

The current implementation of DefaultArtifactVersion in the core of Maven expects that version numbers will have a very specific format:

<MajorVersion [> . <MinorVersion [> . <IncrementalVersion ] ] [> - <BuildNumber | Qualifier ]>

Where MajorVersion, MinorVersion, IncrementalVersion and BuildNumber are all numeric and Qualifier is a string. If your version number does not match this format, then the entire version number is treated as being the Qualifier.

If your version numbers do not match this scheme, you may face issues with

  • version ranges (unfortunately there is nothing that the versions-maven-plugin can do to help you with your problems with version ranges and your version numbering scheme... well you could replace your version ranges with properties and use the update-properties goal)
  • goals in this plugin that sort versions, for example update-properties (you can do things to help with these kinds of problems)

The versions-maven-plugin knows three rules for comparing version numbers:

maven
The standard Maven 2.x version numbering scheme.
numeric
An alternative version numbering scheme with no "special" qualifiers.

The versions-maven-plugin will assume that all version numbers follow the maven scheme unless you tell it otherwise.

Rules.xml

To specify the version schemes to use, you must define a rule-set xml file, for example:

<ruleset comparisonMethod="maven"
         xmlns="http://mojo.codehaus.org/versions-maven-plugin/rule/2.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://mojo.codehaus.org/versions-maven-plugin/rule/2.0.0 https://www.mojohaus.org/versions-maven-plugin/xsd/rule-2.0.0.xsd">
  <rules>
    <rule groupId="*.maven" comparisonMethod="mercury"/>
    <rule groupId="com.mycompany" comparisonMethod="numeric"/>
    <rule groupId="com.mycompany.maven" comparisonMethod="maven"/>
    <rule groupId="com.mycompany.maven" artifactId="old-maven-plugin" comparisonMethod="mercury"/>
  </rules>
</ruleset>

The rule-set files must match the XSD schema.

You can then use the rulesUri parameter to specify the rule-set to be used by the versions-maven-plugin.

Note: the groupId attribute in the rule elements has a lazy .* at the end, such that com.mycompany will match com.mycompany, com.mycompany.foo, com.mycompany.foo.bar, etc.

Ignoring certain versions

It is possible to ignore versions on a global and on a per-rule basis.

<ruleset comparisonMethod="maven"
         xmlns="http://mojo.codehaus.org/versions-maven-plugin/rule/2.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://mojo.codehaus.org/versions-maven-plugin/rule/2.0.0 https://www.mojohaus.org/versions-maven-plugin/xsd/rule-2.0.0.xsd">
  <ignoreVersions>
    <ignoreVersion type="regex">.*-beta</ignoreVersion>
  </ignoreVersions>
  <rules>
    <rule groupId="com.mycompany.maven" comparisonMethod="maven">
      <ignoreVersions>
        <ignoreVersion type="regex">.*-RELEASE</ignoreVersion>
        <ignoreVersion>2.1.0</ignoreVersion>
      </ignoreVersions>
    </rule>
  </rules>
</ruleset>

Note: it is possible to ignore versions using regular expressions.

If you have your ruleset xml file hosted at, for example, http://www.mycompany.com/maven-version-rules.xml then the following configuration in your corporate pom would ensure that all projects use this rule set.

<project>
  ...
  <build>
    ...
    <plugins>
      ...
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>versions-maven-plugin</artifactId>
        <version>2.8.1</version>
        <configuration>
          ...
          <rulesUri>http://www.mycompany.com/maven-version-rules.xml</rulesUri>
          ...
        </configuration>
      </plugin>
      ...
    </plugins>
    ...
  </build>
  ...
</project>

You can provide your ruleset xml file also within a jar, if you want to distribute your ruleset xml as Maven artifact. Therefore you have to declare the containing jar as direct dependency of the versions-maven-plugin and to use classpath as protocol.

<project>
  ...
  <build>
    ...
    <plugins>
      ...
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>versions-maven-plugin</artifactId>
        <version>2.8.1</version>
        <configuration>
          ...
          <rulesUri>classpath:///package/foo/bar/rules.xml</rulesUri>
          ...
        </configuration>
        <dependencies>
            <dependency>
                <groupId>com.mycompany</groupId>
                <artifactId>version-rules</artifactId>
                <version>1.0</version>
            </dependency>
        </dependencies>
      </plugin>
      ...
    </plugins>
    ...
  </build>
  ...
</project>