versions-maven-plugin How to ignore alpha beta release candidate and milestone versions

versions-maven-plugin ignore versions.md

versions-maven-plugin: How to ignore alpha, beta, release candidate, and milestone versions

Introduction

The versions-maven-plugin, by default, does not ignore versions ending with qualifier strings when searching for the latest version of an artifact.

For example, versions ending with -alpha.14, -beta3, -M-2, and -RC1 will be considered as valid upgrade candidates.

Suppose your project depends on version 3.2.1 of a certain artifact and then 3.3.0-beta is released. The versions-maven-plugin will, by default, consider that to be a valid upgrade.

To make versions-maven-plugin ignore such qualified versions read on.

What about SNAPSHOT releases? How do I ignore those?

There's no need to create a rule to ignore SNAPSHOT releases because the allowSnapshots configuration parameter is false by default.

Difficult way: Create a rules.xml file

Based on:

• Version number rules § Rules.xml
  https://www.mojohaus.org/versions/versions-maven-plugin/version-rules.html
• How to display dependency updates only for release versions
  https://stackoverflow.com/q/38146719

Make a file next to your pom called, say, versions-ruleset.xml:

<?xml version="1.0" encoding="UTF-8"?>
<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>
        <!-- Ignore Alpha's, Beta's, release candidates and milestones -->
        <ignoreVersion type="regex">(?i).*-alpha([-.]?\d+)?</ignoreVersion>
        <ignoreVersion type="regex">(?i).*-beta([-.]?\d+)?</ignoreVersion>
        <ignoreVersion type="regex">(?i).*-rc([-.]?\d+)?</ignoreVersion>
        <ignoreVersion type="regex">(?i).*-m([-.]?\d+)?</ignoreVersion>
    </ignoreVersions>
    <rules>
      <!-- You can add more specific rules here -->
    </rules>
</ruleset>

Explanation of the regex (refer to Java 8 regex documentation):

• (?i) — sets the case-insensitive flag
• .* — zero or more characters
• - — hyphen
• alpha — the literal string alpha
• (...)? — optional group, contents of which follow
  • [-.]? — optional hyphen or dot
  • \d+ — one or more digits

Note: these regex patterns, like glob patterns, are tested against the whole version string. This is similar to how grep's -x, --line-regexp option behaves: it is "like parenthesizing the pattern and then surrounding it with ^ and $."

We can simplify this configuration by making use of alternation in the regex:

<?xml version="1.0" encoding="UTF-8"?>
<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>
        <!-- Ignore Alpha's, Beta's, release candidates and milestones -->
        <ignoreVersion type="regex">(?i).*-(alpha|beta|rc|m)([-.]?\d+)?</ignoreVersion>
    </ignoreVersions>
    <rules>
      <!-- You can add more specific rules here -->
    </rules>
</ruleset>

Once you have your versions-ruleset.xml file prepared, you must reference it in the versions-maven-plugin configuration in your pom's pluginManagement section.

pom.xml: project > build > pluginManagement:

<plugin>
  <groupId>org.codehaus.mojo</groupId>
  <artifactId>versions-maven-plugin</artifactId>
  <version>2.8.1</version>
  <configuration>
    <rulesUri>file:///${project.basedir}/versions-rules.xml</rulesUri>
  </configuration>
</plugin>

Easier way: Using the ruleSet element directly in the POM

[S]tarting with version 2.13.0 it is possible to provide the ruleSet element directly in the POM

Using the ruleSet element in the POM

<plugin>
  <groupId>org.codehaus.mojo</groupId>
  <artifactId>versions-maven-plugin</artifactId>
  <version>2.13.0</version>
  <configuration>
    <ruleSet>
      <ignoreVersions>
        <ignoreVersion>
          <type>regex</type>
          <version>(?i).*-(alpha|beta|m|rc)([-.]?\d+)?</version>
        </ignoreVersion>
      </ignoreVersions>
    </ruleSet>
  </configuration>
</plugin>

Even easier way: new parameter ignoredVersions

<plugin>
  <groupId>org.codehaus.mojo</groupId>
  <artifactId>versions-maven-plugin</artifactId>
  <version>2.13.0</version>
  <configuration>
    <ignoredVersions>(?i).*-(alpha|beta|m|rc)([-.]?\d+)?</ignoredVersions>
  </configuration>
</plugin>

Note: You may put multiple regular expressions in this configuration parameter by separating them with commas.

Learn more:

• ignoredVersions (since 2.13.0)
  https://www.mojohaus.org/versions/versions-maven-plugin/display-dependency-updates-mojo.html#ignoredVersions
• Using the maven.version.ignore property
  https://www.mojohaus.org/versions/versions-maven-plugin/version-rules.html#using-the-maven-version-ignore-property

Using the maven.version.ignore property

The aforementioned ignoredVersions parameter has a corresponding user property: maven.version.ignore .

You can specify the maven.version.ignore property in your pom.xml or on the command line, just like any other property.

Example of using it in pom.xml:

pom.xml: project > properties:

<maven.version.ignore>(?i).*-(alpha|beta|m|rc)([-.]?\d+)?</maven.version.ignore>

Example of using it on the command line:

./mvnw -U -Dmaven.version.ignore='(?i).*-(alpha|beta|m|rc)([-.]?\d+)?' versions:display-plugin-updates 

The -U, --update-snapshots option "forces a check for missing releases and updated snapshots on remote repositories." You might find it necessary to use this option to accurately reflect the latest releases on remote maven repositories—at least as a temporary workaround. See discussions:

• Versions Maven Plugin not showing latest plugins available with ignores. #959
  mojohaus/versions#959
• Maven Artifact Resolver not seeing latest plugins on Maven Central on my machine
  https://stackoverflow.com/q/76307809
• Not detecting numerous Plugins updates available #415
  mojohaus/versions#415

Tip: comparing version strings

You can compare version strings using the maven-artifact.jar:

$ java -jar maven-artifact.jar 3.2.1 3.2.1-beta
Display parameters as parsed by Maven (in canonical form and as a list of tokens) and comparison result:
1. 3.2.1 -> 3.2.1; tokens: [3, 2, 1]
   3.2.1 > 3.2.1-beta
2. 3.2.1-beta -> 3.2.1-beta; tokens: [3, 2, 1, [beta]]

$ java -jar maven-artifact.jar 3.2.1 3.3.0-beta
Display parameters as parsed by Maven (in canonical form and as a list of tokens) and comparison result:
1. 3.2.1 -> 3.2.1; tokens: [3, 2, 1]
   3.2.1 < 3.3.0-beta
2. 3.3.0-beta -> 3.3-beta; tokens: [3, 3, [beta]]

As seen in these discussions:

• display-dependency-updates version comparison algorithm bug for -pfd
  mojohaus/versions#744
• Legit but Useless: Maven Version Ranges Explained | by Michael Kutz | Medium
  https://michakutz.medium.com/legit-but-useless-maven-version-ranges-explained-d4ba66ac654

RegexTest.java

import java.util.regex.Pattern;
import java.util.regex.Matcher;

public class RegexTest {
    public static void main(String[] args) {
        String regex = "(?i).*-(alpha|beta|m|rc)([-.]?\\d+)?";
        String[] inputs = {
            "1.2.3",
            "1.3.0-alpha",
            "1.3.0-alpha.15",
            "1.3.0-beta",
            "1.3.0-beta-2",
            "1.3.0-rc3",
            "1.3.0-M1"
        };

        Pattern pattern = Pattern.compile(regex);

        // Print the headers
        System.out.printf("%-20s %-20s%n", "Input string", "Regex matches?");
        System.out.printf("%-20s %-20s%n", "------------", "-------------");

        // Iterate through the input strings and check if they match the regex
        for (String input : inputs) {
            Matcher matcher = pattern.matcher(input);
            String result = matcher.matches() ? "Yes" : "No";
            System.out.printf("%-20s %-20s%n", input, result);
        }
    }
}

Output:

Input string         Regex matches?      
------------         -------------       
1.2.3                No                  
1.3.0-alpha          Yes                 
1.3.0-alpha.15       Yes                 
1.3.0-beta           Yes                 
1.3.0-beta-2         Yes                 
1.3.0-rc3            Yes                 
1.3.0-M1             Yes            

Great write-up. If you'd like to catch more alpha variations like OkHttp's naming conventions, consider the modified regex:

<maven.version.ignore>(?i).*-(alpha|beta|m|rc)([\.-]?\d+)?</maven.version.ignore>

This will ignore both variations (both dot-delimited and hyphen-delimited suffixes):

com.squareup.okhttp3:okhttp ................. 4.12.0 -> 5.0.0-alpha.14
io.sample:sample ............................ 0.10.5 -> 1.0.0-alpha-4

Thanks @scriptam! I incorporated your suggestion.

is there a command line version so that we dont have to modify every project where we need to upgrade the poms?

Not sure about your project structure but in my case using rules.xml on project root directory followed by just using maven for updating suffices.

Check which updates will take effect:

mvn versions:display-dependency-updates

Auto-updating pom.xml:

mvn versions:use-latest-versions

(The old version is typically backed up to pom.xml.versionsBackup)

mvn org.codehaus.mojo:versions-maven-plugin:2.18.0:use-latest-versions -Dmaven.version.ignore='.*alpha.*,.*beta.*,.*rc.*'

This command line will do the job without needing any modifications to pom.xmls or creating rules.xml