[MNG-7559] Fix version comparison with case insensitive lexical order

[sultan]

This PR description was edited to reflect its latest status:

Recurring issues show that Maven’s current handling of qualifiers is incomplete, impacting multiple companies and users:

• display-dependency-updates version comparison algorithm bug for -pfd mojohaus/versions#744
• [MNG-7559] ComparableVersion vs versions with custom qualifiers maven#8891
• fix: mark version with "preview" extension as pre-release (#6151) dependabot/dependabot-core#6747
• Treat -pre version suffix as prerelease. dependabot/dependabot-core#10207

These issues need to be addressed in Maven Resolver. I am working to encourage Maven to adopt a fix through this PR.

Proposed ordering:

• alpha < beta < milestone < pr = pre = preview < rc = cr < dev < snapshot < final = ga = release < sp

I edited the documentation to discourage the use of certain qualifiers:

• The use of pr, pre, preview is discouraged
• The use of cr is discouraged (use rc instead)
• The use of dev is discouraged
• The use of final, ga, release is discouraged (use no qualifier instead)
• The use of sp is discouraged (increment patch version instead)

Optional inclusions:

• ea (early access), edr, pfd (drafts), mr

As long as discouraged qualifiers continue to be used in practice, tools will still need to support them. Once they are phased out, however, support can be safely dropped.

Another possible direction would be:

• Partial SemVer2 support, which could simplify handling of qualifiers:
  • Accept the "+" char as a separator.
  • Temporarily treat discouraged qualifiers as follows (while discouraging their use when necessary):
    • latest pre-release: dev, snapshot
    • release: final, ga, release
    • post-release: sp
  • Treat all other qualifiers as pre-release without hard-coding them, reducing the number of special cases.
  • Use aliases/mapping:
    • a to alpha
    • b to beta
    • m to milestone
    • cr to rc
    • "final", "ga", "release" to ""
• Maven could force the build to fail if any module uses discouraged qualifiers.
• Maven Central could begin rejecting new artifacts using discouraged qualifiers.

Thanks for your input.

---

Following this checklist to help us incorporate your
contribution quickly and easily:

• Your pull request should address just one issue, without pulling in other changes.
• Write a pull request description that is detailed enough to understand what the pull request does, how, and why.
• Each commit in the pull request should have a meaningful subject line and body.
  Note that commits might be squashed by a maintainer on merge.
• Write unit tests that match behavioral changes, where the tests fail if the changes to the runtime are not applied.
  This may not always be possible but is a best-practice.
• Run mvn verify to make sure basic checks pass.
  A more thorough check will be performed on your pull request automatically.
• You have run the integration tests successfully (mvn -Prun-its verify).

If your pull request is about ~20 lines of code you don't need to sign an Individual Contributor License Agreement if you are unsure please ask on the developers list.

To make clear that you license your contribution under the Apache License Version 2.0, January 2004 you have to acknowledge this by using the following check-box.

• I hereby declare this contribution to be licenced under the Apache License Version 2.0, January 2004
• In any other case, please file an Apache Individual Contributor License Agreement.

[cstamas]

pls check the up to date spec for resolver versions:
https://github.com/apache/maven-resolver/blob/60ee5c0902167d7f52545645c67b0ad531c66bca/maven-resolver-util/src/main/java/org/eclipse/aether/util/version/package-info.java

[sultan]

for reference :

• spec is spread among:
  • https://maven.apache.org/pom.html#version-order-specification
  • https://github.com/apache/maven-resolver/blob/master/maven-resolver-util/src/main/java/org/eclipse/aether/util/version/package-info.java
  • https://github.com/apache/maven-resolver/blob/master/maven-resolver-util/src/main/java/org/eclipse/aether/util/version/GenericVersionScheme.java
• this issue : [MNG-7559] ComparableVersion vs versions with custom qualifiers maven#8891
• the need to have : preview < release

this PR might need to be split into 2 PRs

• one to fix preview < release
• one to add SemVer2 in a different comparer ? (not the default one)

[sultan]

we have to discuss how to address the other discouraged qualifiers used in java ee / jarktaee:

• release > ea (= early access) see https://mvnrepository.com/artifact/javax.xml.bind/jaxb-api?p=2
• release > edr, pfd (d=draft) see https://mvnrepository.com/artifact/javax.faces/javax.faces-api
• release > mr (=milestone release) > RC see https://mvnrepository.com/artifact/jakarta.inject/jakarta.inject-api

in order to fix all the encountered problems. or state on website/javadoc that this will be a no-fix

intend to fix apache/maven#8891 step by step
this PR fixes the following "discouraged qualifiers" :

• "pr" = "pre" = "preview" < (rc) < "dev" < (snapshot) < "final" = "ga" = "release"

[elharo]

IMPORTANT: https://maven.apache.org/pom.html#Version_Order_Specification is the one and only normative source for maven version comparison.

If there are any bugs in this, file them, one issue per bug.

However, the default assumption is that if the code or other docs differ from what is described here, then it is the code or other doc that is at fault and needs to be changed.

[elharo]

Maven does not, cannot, and will not special case every qualifier any project has ever invented. In particular it does not special case:

• pr
• preview
• pre
• dev

They are treated like any other string as described in https://maven.apache.org/pom.html#Version_Order_Specification

[sultan]

Thank you for clarifying the current handling of qualifiers.
This may be acceptable, but IMHO it would be great if Maven could provide more explicit reasoning and guidance:

• Clarification of rationale: Could you explain why certain qualifiers (e.g. sp from Red Hat) are accepted, while others (like preview from Microsoft or dev from Android) are not? Is this distinction based on legacy behaviour tied to the date of introduction of qualifiers, or on community adoption patterns?
• Version ordering issues: Will the ordering problems that arise from these differences be considered “no fix”, or is there room for improvement in the resolver logic?
• Specification transparency: It would help if Maven documented this behaviour in the specification, with the reasoning included, so that users don’t repeatedly open issues about unexpected ordering.
• Alternative schemes: Would Maven be open to supporting a second version scheme alongside the Generic one, to address these ordering problems more systematically?
• Ecosystem guidance: Would Maven recommend that tools like Dependabot define their own version scheme to handle these ordering inconsistencies, or should the community expect Maven itself to provide a canonical solution?
• Statement to vendors: Could Maven also consider making a clear statement to major vendors, encouraging them to avoid problematic qualifiers? For example:
  • Microsoft → stop using preview
  • Red Hat → avoid ga and sp1
  • Android → avoid dev
  • (Positive example: Spring stopped using the release qualifier and aligned with best practices)

Such a statement would help reduce confusion across the ecosystem and promote consistent versioning practices.

[gnodet]

AI Review — PR #1683: Fix version comparison with case insensitive lexical order

Hi @sultan, thanks for the effort on improving version comparison!

After reviewing the current state of this PR against master, there are several blockers:

🔴 Merge conflicts — code has been refactored (high)

This PR modifies qualifier constants in GenericVersion.java's Tokenizer inner class, but since April 2026 (commit 283b542), those constants have been extracted to a new public class GenericQualifiers.java. The PR is in a CONFLICTING merge state and targets code that no longer exists on master.

🔴 Maintainer rejected adding new qualifiers (high)

A maintainer (@elharo) has explicitly rejected the addition of "pr", "pre", "preview", and "dev" as special-cased qualifiers via a CHANGES_REQUESTED review, stating: "Maven does not, cannot, and will not special case every qualifier any project has ever invented."

🔴 Renumbering breaks public API (high)

The proposed changes renumber QUALIFIER_ALPHA (-5 → -7), QUALIFIER_BETA (-4 → -6), and QUALIFIER_MILESTONE (-3 → -5). On master, these are now public API constants in GenericQualifiers.java (introduced as @since 2.0.17). Changing their values would be a breaking change for downstream consumers.

⚠️ Commented-out test assertions (medium)

testMng7559 contains three commented-out assertion lines, suggesting incomplete implementation or untested edge cases.

💡 Test method visibility inconsistency (low)

testMng7714 is declared public void while all other test methods in the file use package-private visibility (void).

Given the maintainer's explicit rejection and the fundamental code conflicts, this PR would need a complete rethink to move forward.

---

🤖 This review was generated by ForgeBot using a maker/checker pattern (reviewer + independent verifier). All findings were independently confirmed.

[gnodet]

Review Summary

Thanks for the effort on this, @sultan. However, this PR has two independently blocking issues that prevent it from being merged in its current state.

Merge Conflicts (confirmed)

The PR modifies qualifier constants (QUALIFIER_ALPHA, QUALIFIER_BETA, QUALIFIER_MILESTONE) and the QUALIFIERS map inside GenericVersion.java's Tokenizer inner class, but on master these have been extracted to a new public class GenericQualifiers.java (commit 283b542, April 2026). GitHub confirms the merge state is CONFLICTING. The PR would need to be rebased against current master, with changes targeting GenericQualifiers.java instead.

Maintainer Feedback Not Addressed (confirmed)

@elharo submitted an explicit CHANGES_REQUESTED review stating: "Maven does not, cannot, and will not special case every qualifier any project has ever invented. In particular it does not special case: pr, preview, pre, dev." The PR still adds exactly these four qualifiers. This maintainer feedback would need to be addressed before the PR can proceed.

Additional Observations

• Commented-out test assertions in testMng7559 (3 lines) suggest the implementation may not fully handle all stated goals.
• Minor style: testMng7714() uses public void while all other test methods use package-private visibility.
• Some documentation changes (reversing ordering notation in package-info.java) are cosmetic and add noise to the diff without changing semantics.

Suggestion

Some of the regression tests added (e.g., testMng5568, testMng6572, testMng6964, testMng7644) verify behaviors that should already pass on master. These could be valuable regression tests on their own and might be contributed as a separate, smaller PR.

---

This review was generated by an AI agent and may contain inaccuracies. Please verify all suggestions before applying.

Claude Code on behalf of Guillaume Nodet