[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.