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 the Maven Version Order Specification 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 and 3.x version numbering scheme.
numeric, An alternative version numbering scheme with no “special” qualifiers.
mercury, An alternative version numbering scheme, now defunct.

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 may define a rule-set xml file, use the ruleSet element in the versions-maven-plugin plugin configuration, or specify ignored versions via the maven.version.ignore property.

Using the `rules.xml` file

The rules.xml file should conform to the xsd specified in the example below.

<ruleset comparisonMethod="maven"
         xmlns="https://www.mojohaus.org/VERSIONS/RULE/2.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="https://www.mojohaus.org/VERSIONS/RULE/2.1.0 https://www.mojohaus.org/versions/versions-model/xsd/rule-2.1.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.

Using the `ruleSet` element in the POM

As an alternative to providing a separate rules.xml file, starting with version 2.13.0 it is possible to provide the ruleSet element directly in the POM. The structure is somewhat simpler to the rules.xml file:

<project>
  ...
  <build>
    ...
    <plugins>
      ...
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>versions-maven-plugin</artifactId>
        <version>2.18.0</version>
        <configuration>
          <ruleSet>
            <!-- zero or more elements -->
            <ignoreVersions>
              <!-- zero or more elements -->
              <ignoreVersion>
                <version>1.0.0</version>
              </ignoreVersion>
              <ignoreVersion>
                <!-- can be either: 'exact' (default), 'regex' or 'range' -->
                <type>regex</type>
                <version>(.+-SNAPSHOT|.+-M\d)</version>
              </ignoreVersion>
              <ignoreVersion>
                <type>regex</type>
                <version>.+-(alpha|beta).+</version>
              </ignoreVersion>
              <ignoreVersion>
                <type>range</type>
                <version>[2.0,)</version>
              </ignoreVersion>
            </ignoreVersions>

          <!-- zero or more elements -->
          <rules>
            <!-- zero or more elements -->
            <rule>
              <!-- if provided, restricts the groupId for the rule -->
              <groupId>org.codehaus.mojo</groupId>

              <!-- if provided,
              <artifactId>versions-maven-plugin</artifactId>

              <!-- syntax the same as for the general ignoreVersions -->
              <ignoreVersions>
                ...
              </ignoreVersions>

              <!-- optional, comparison method for the rule, one of: maven (default), numeric, mercury -->
              <comparisonMethod>maven</comparisonMethod>
            </rule>
          </rules>
      </ruleSet>

Using the `maven.version.ignore` property

The maven.version.ignore property can list comma-separated list of global version regex patterns, which will be ignored when considering available versions.

Examples:

1.0.0
.+-SNAPSHOT
(.+-SNAPSHOT|.+-M\d),.+-(alpha|beta).+,3.0.0

Ignoring certain versions

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

The other methods (via the <ruleSet> element and via the maven.version.ignore) property have been explained above. The described

<ruleset comparisonMethod="maven"
         xmlns="https://www.mojohaus.org/VERSIONS/RULE/2.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="https://www.mojohaus.org/VERSIONS/RULE/2.1.0 https://www.mojohaus.org/versions/versions-model/xsd/rule-2.1.0.xsd">
  <ignoreVersions>
    <ignoreVersion type="regex">.*-beta</ignoreVersion>
  </ignoreVersions>
  <rules>
    <rule groupId="com.mycompany.maven" comparisonMethod="maven">
      <ignoreVersions>
        <ignoreVersion type="regex">.*-RELEASE</ignoreVersion>
        <ignoreVersion type="range">[2.0.0,)</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.18.0</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.18.0</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>