elharo commented on code in PR #1714:
URL: https://github.com/apache/maven-resolver/pull/1714#discussion_r2623029810
##########
maven-resolver-util/src/main/java/org/eclipse/aether/util/version/package-info.java:
##########
@@ -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>.
Review Comment:
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 block 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. :-(
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
