Skip to content

Edit version comparison #1714

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
elharo wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Edit version comparison #1714

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
12186fc
Edit version comparison
elharo Dec 15, 2025
91cc293
undefined
elharo Dec 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 10 additions & 10 deletions maven-resolver-util/src/main/java/org/eclipse/aether/util/version/package-info.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,22 +21,22 @@
* Version scheme for parsing/comparing versions and utility classes.
* <p>
* Contains the "generic" scheme {@link org.eclipse.aether.util.version.GenericVersionScheme}
* that serves the purpose of "factory" (and/or parser) for all corresponding elements (all those are package private).
* that serves as a "factory" (and/or parser) for corresponding package private classes.
* <p>
* On the other hand, the {@link org.eclipse.aether.util.version.UnionVersionRange} is universal implementation of
* On the other hand, the {@link org.eclipse.aether.util.version.UnionVersionRange} is a universal implementation of
* "unions" of various {@link org.eclipse.aether.version.VersionRange} instances.
* <p>
* Below is the <em>Generic Version Spec</em> described:
* <p>
* Version string is parsed into version according to these rules:
* A version string is parsed according to the
* <href='https://maven.apache.org/pom.html#Version_Order_Specification'>Version Order Specification</a>.
Copy link
Member

@cstamas cstamas Dec 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nope. The refd URL points to maven-artifact spec, that is known to differ from this one (see resolver/maven issues). In Maven 4 the Resolver Version is becoming "the standard" (as new Maven4 API delegates to it), and maven-artifact module is put under compat/, as it is being deprecated with many other things there.

Goal is to stop this current split-brain situation, and duplication of this very important aspect of Maven. Moreover, maven-artifact class Artifact is basically a mixed bag of dependencies (has scope etc) and artifacts. That thing should be just forgotten.

Copy link
Member

@cstamas cstamas Dec 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Or, align the site page with Resolver GenericVersion, then it could be fine to point there.

But the goal is to stop having this duality, duplication and keep trying to align these two classes, aside maven-artifact one is being totally overloaded with other things as well. Just stop pouring energy into it.

Copy link
Contributor Author

@elharo elharo Dec 16, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, the goal here is precisely to stop the split brain problem where different docs say different things and sometimes contradict each other. The page in question at https://maven.apache.org/pom.html#Version_Order_Specification is the primary Maven documentation from the maven-site repository. It is not tied to maven-artifact, maven-resolver, or any other plugin or particular code. That's important since this is used and depended on by multiple projects. Most importantly this is user documentation for anyone who needs to understand why a dependency tree is resolving the way it is.

It is also important to provide a normative spec for anyone implementing this. For historical reasons, this is a little backwards and some of this is reverse engineered from what the code has been doing for over two decades now rather than planned out up front. Ideally we would have started with a clear and unambiguous spec and built the implementation from that.

Going forward, any additional implementations should start from the spec rather than trying to duplicate code or algorithms. (Yes, other implementations do exist outside the maven project.) I also want to prevent unconsidered changes to the algorithm that sneak in through random PRs. Example: min/max version specifiers that got added 12 years ago, introduced a new supply chain attack, and don't seem to have ever been documented. :-(

* These rules are summarized here :
* <ul>
* <li>The version string is parsed into segments, from left to right.</li>
* <li>Segments are explicitly delimited by a single {@code "." (dot)}, {@code "-" (hyphen)}, or {@code "_" (underscore)} character.</li>
* <li>Segments are implicitly delimited by a transition between ASCII digits and non-digits.</li>
* <li>Segments are classified as numeric, string, qualifiers (special case of string), and min/max.</li>
* <li>Numeric segments are composed of the ASCII digits 0-9. Non-ASCII digits are treated as letters.
* <li>Numeric segments are sorted numerically, ascending.</li>
* <li>Non-numeric segments may be qualifiers (predefined) or strings (non-empty letter sequence). All of them are interpreted as being case-insensitive in terms of the ROOT locale.</li>
* <li>Non-numeric segments may be qualifiers (predefined) or strings (non-empty letter sequence). All of them are interpreted as being case-insensitive in the ROOT locale.</li>
* <li>Qualifier segments (strings listed below) and their sort order (ascending) are:
* <ul>
* <li>"alpha" (== "a" when immediately followed by number)</li>
Expand All @@ -52,16 +52,16 @@
* <li>There are two special segments, {@code "min"} and {@code "max"} that represent absolute minimum and absolute maximum in comparisons. They can be used only as the trailing segment.</li>
* <li>As last step, trailing "zero segments" are trimmed. Similarly, "zero segments" positioned before numeric and non-numeric transitions (either explicitly or implicitly delimited) are trimmed.</li>
* <li>When trimming, "zero segments" are qualifiers {@code "ga"}, {@code "final"}, {@code "release"} only if being last (right-most) segment, empty string and "0" always.</li>
* <li>In comparison of same kind segments, the given type of segment determines comparison rules.</li>
* <li>In comparison of different kind of segments, following applies: {@code max > numeric > string > qualifier > min}.</li>
* <li>When comparing the same kind of segments, the type of segment determines comparison rules.</li>
* <li>When comparing different kinds of segments, the following applies: {@code max > numeric > string > qualifier > min}.</li>
* <li>Any version can be considered to have an infinite number of invisible trailing "zero segments", for the purposes of comparison (in other words, "1" == "1.0.0.0.0.0.0.0.0....")</li>
* <li>It is common that a version identifier starts with numeric segment (consider this "best practice").</li>
* </ul>
* <p>
* Note: this version spec does not document (or cover) many corner cases that we believe are "atypical" or not
* used commonly. None of these are enforced, but in future implementations they probably will be. Some known examples are:
* commonly used. Some known examples are:
* <ul>
* <li>Using "min" or "max" special segments as a non-trailing segment. This yields in "undefined" behaviour and should be avoided.</li>
* <li>Using "min" or "max" special segments as a non-trailing segment. Comparisons with such strings are "undefined" and should be avoided.</li>
* <li>Having a non-number as the first segment of a version. Versions are expected (but not enforced) to start with numbers.</li>
* </ul>
*/
Expand Down