Hi, I opened https://issues.apache.org/jira/browse/MNGSITE-300 to improve the documentation of the version order. Cheers, Jon
Jon On Mon, Mar 23, 2015 at 6:39 PM, Jon Harper <jon.harpe...@gmail.com> wrote: > Hi Hervé, > thanks. I agree that the intro is now better, but I think we need to > describe the order more precisely. The problem is that the order is quite > complex, so maybe this can be moved to another main apt page (different > than the designs docs (they are not documentation) > http://docs.codehaus.org/display/MAVEN/Versioning or > http://docs.codehaus.org/display/MAVEN/Dependency+Mediation+and+Conflict+ > Resolution, or javadoc (it changes to often, too tied to the > implementation) https://maven.apache.org/ref/3.3.1/maven-artifact/apidocs/ > org/apache/maven/artifact/versioning/ComparableVersion.html) > > Anyway, here's the "simplest" description I could come up with regarding > the algorithm to select the effective version. This is a first draft, so > whole parts could be changed. Hopefully something good comes out of it. > > Regards, > Jon > > Index: pom.apt > =================================================================== > --- pom.apt (révision 1668633) > +++ pom.apt (copie de travail) > @@ -402,8 +402,18 @@ > *** {Dependency Version Requirement Specification} > > Dependencies' <<<version>>> element define version requirements, used > to compute effective dependency > - version. Version requirements have the following syntax: > + version. The effective dependency version is the highest version > (lexicographically > + according to the presence of a Soft Requirement, and then Versionning > Order) of the set of available > + artifacts, intersected with all declared version requirement ranges. > > + Version requirements syntax: > + version_requirement = element ( "," element )* # a version > requirement is a comma-separated set of at least 1 element > + element = maven_coordinate | range # an element is either a plain > maven coordinate or a range > + range = range_open (maven_coordinate)? "," (maven_coordinate)? > range_close # all versions between optional low and high boundaries; a > missing boundary means -/+ Infinity > + range_open = "[" | "(" # "[" includes the low boundary, "(" > excludes the low boundary > + range_close = "]" | ")" # "]" includes the high boundary, ")" > excludes the high boundary > + > + Version requirements semantics: > * <<<1.0>>>: "Soft" requirement on 1.0 (just a recommendation, if it > matches all other ranges for the dependency) > > * <<<[1.0]>>>: "Hard" requirement on 1.0 > @@ -420,6 +430,38 @@ > > * <<<(,1.1),(1.1,)>>>: this excludes 1.1 (for example if it is known > not to work in combination with this library) > > + Versionning order: > + The maven coordinate is tokenized on ".", "-" and the transitions > between digits/character > + (equivalent to a "-" character). Empty tokens are replaced with "0". > + This gives a sequence of version numbers (numeric tokens) and version > qualifiers (non-numeric tokens) > + with "." or "-" prefixes. The trailing "null" prefix values are > removed: 0 for numbers, "" and "final" and "ga" for qualifiers. > + The order is the lexicographical order on this sequence of prefixed > tokens, the shorter one > + padded with enough "null" values with matching prefix to have the > same length as the longer one. > + The prefixed token order is: > + * if the prefix is the same, then compare the token: > + * Numeric tokens have the natural order. > + * Non-numeric ("qualifiers") tokens have the alphabetical order, > except for the following tokens which come first in this order: > + "alpha" = "a" \< "beta" = "b" \< "milestone" = "m" \< "rc" = "cr" \< > + "snapshot" \< "" = "final" = "ga" \< "sp" > + * else ".qualifier" < "-qualifier" < "-number" < ".number" > + > + Examples: > + * "1" = "1.0.0" < 1.0.1 (number padding) > + * "1-snapshot" < "1" < "1-sp" (qualifier padding, remember the null > value for qualifiers has special order) > + * "1-foo2" = "1-foo-2" < "1-foo10" = "1-foo-10" (transition correctly > "switches" back to numeric order) > + * "1.foo" < "1-foo" < "1-1" < "1.1" > + * "1.0" = "1-0" = "1" = "1-" = "1-ga" = "1-final" (removing of > trailing "null" values) > + * "1.sp.1" < "1-.1" (empty token replaced by the number 0, not by > the null value ""!) > + * Complex example > + * "1.0" < "1.sp" (trailing null value removed, padded to identifier > null, which is less than sp) > + * "1.sp.1" < "1.0.1" ( .sp < .0 because ".qualifier" < ".number") > + > + Note1: Contrary to what was stated in some design documents, snapshots > are not treated differently than releases or any other qualifier. > + Note2: The Versionning Order quickly becomes complex unless you stick > with "sane" versions. > + > + > + > + > *** {Exclusions} > > Exclusions explicitly tell Maven that you don't want to include the > > > > Jon > > On Sun, Mar 22, 2015 at 5:18 PM, Hervé BOUTEMY <herve.bout...@free.fr> > wrote: > >> Hi Jon, >> >> Thank you for your great proposal. >> I fixed some formatting issues and integrated it: I think the intro is now >> better >> >> Regards, >> >> Hervé >> >> Le vendredi 20 mars 2015 19:28:24 Jon Harper a écrit : >> > Hi Hervé, >> > what do you think of the following first patch ? I haven't generated the >> > corresponding html yet, just throwing some ideas.. >> > >> > Regards, >> > Jon >> > >> > Index: pom.apt >> > =================================================================== >> > --- pom.apt (révision 1668105) >> > +++ pom.apt (copie de travail) >> > @@ -303,8 +303,14 @@ >> > +-----------------+ >> > >> > * <<groupId>>, <<artifactId>>, <<version>>:\ >> > - These elements are self-explanatory, and you will see them often. >> This >> > trinity represents the coordinate >> > - of a specific project in time, demarcating it as a dependency of this >> > project. You may be thinking: >> > + You will see these elements often. This trinity is used to compute >> the >> > maven coordinate >> > + of a specific project in time, demarcating it as a dependency of this >> > project. The purpose >> > + of this computation is to select a version that matches all the >> > dependency declarations >> > + (due to transitive dependencies, there can be multiple dependency >> > declarations for the >> > + same artifact). The values should be: >> > + * <<groupID>>, <<artifactID>>: directly the corresponding >> coordinates >> > of the dependency. >> > + * <<version>>: a <<version range>> that will be used to compute the >> > dependency's version. >> > + Since the dependency is described by maven coordinates, you may be >> > thinking: >> > "This means that my project can only depend upon Maven artifacts!" >> The >> > answer is, "Of course, but that's a >> > good thing." This forces you to depend solely on dependencies that >> Maven >> > can manage. There are times, >> > unfortunately, when a project cannot be downloaded from the central >> > Maven repository. For example, a project >> > @@ -388,6 +394,21 @@ >> > In the shortest terms, <<<optional>>> lets other projects know that, >> > when you use this project, you >> > do not require this dependency in order to work correctly. >> > >> > +*** {Version Ranges} >> > + >> > + Version Ranges used for the <<version>> element have the following >> > syntax (TODO only examples??): >> > + * 1.0: "Soft" requirement on 1.0 (just a recommendation - helps >> select >> > the correct version if it matches all ranges) >> > + * (,1.0]: x <= 1.0 >> > + * [1.0]: Hard requirement on 1.0 >> > + * [1.2,1.3]: 1.2 <= x <= 1.3 >> > + * [1.0,2.0): 1.0 <= x < 2.0 >> > + * [1.5,): x >= 1.5 >> > + * (,1.0],[1.2,): x <= 1.0 or x >= 1.2. Multiple sets are >> comma-separated >> > + * (,1.1),(1.1,): This excludes 1.1 if it is known not to work in >> > combination with this library >> > + >> > + TODO: describe the pseudo-lexicographical order used above, using >> major >> > version, minor version, incremental version, and qualifier. >> > + examples: 1.0.0-SNAPSHOT < 1.0.0 ... >> > + >> > *** {Exclusions} >> > >> > Exclusions explicitly tell Maven that you don't want to include the >> > >> > >> > Jon >> > >> > On Sun, Feb 15, 2015 at 10:09 PM, Hervé BOUTEMY <herve.bout...@free.fr> >> > >> > wrote: >> > > Hi Jon, >> > > >> > > Le dimanche 15 février 2015 21:41:52 Jon Harper a écrit : >> > > > Hi, >> > > > since there were no answers, I'm not sure I wrote to the correct >> mailing >> > > > list for this problem. >> > > >> > > good mailing list, but can of worm :) >> > > >> > > > Can anyone direct me to someone who is interested in >> > > > working on this issue ? >> > > >> > > I can try to work on this once more: perhaps we'll manage to improve >> > > something >> > > >> > > > For info, the docs have been saying the following for 7+ years: >> > > > "groupId, artifactId, version: >> > > > These elements are self-explanatory" >> > > > >> > > > The version element is *not* self-explanatory, especially regarding >> > > > interactions between version ranges and *-SNAPSHOTs artifacts. >> > > >> > > you're right: version *in dependencies* is not self explanatory >> (version >> > > in >> > > Maven coordinates is self explanatory) >> > > It has a lot of subtle features: preferred vs exact match, version >> range, >> > > then >> > > the question of SNAPSHOTS >> > > >> > > > Any thoughts on this matter would be appreciated. >> > > >> > > if you have little patches for the source of the page [1], I can >> review >> > > and we >> > > can work and discuss on it step by step >> > > >> > > Regards, >> > > >> > > Hervé >> > > >> > > [1] https://svn.apache.org/repos/asf/maven/site/trunk/content/ >> apt/pom.apt >> > > >> > > > Regards, >> > > > Jon >> > > > >> > > > On Thu, Feb 5, 2015 at 5:52 PM, Jon Harper <jon.harpe...@gmail.com> >> > > >> > > wrote: >> > > > > Hi, >> > > > > I'm resurrecting this old thread to ask if it's possible to change >> > > > > http://maven.apache.org/pom.html to document the current >> > > >> > > implementation >> > > >> > > > > behavior (7+ years old). >> > > >> > > > > Please see my comment on MNG-3092: >> > > http://jira.codehaus.org/browse/MNG-3092? >> focusedCommentId=362616&page=com. >> > > >> > > atlassian.jira.plugin.system.issuetabpanels:comment- >> tabpanel#comment-36261 >> > > >> > > > > 6 >> > > > > >> > > > > Jon >> > > > > >> > > > > Mark Hobson Fri, 06 Jul 2007 06:53:04 -0700 >> > > > > >> > > > > > Hi, >> > > > > > >> > > > > > Whilst attempting to fix MNG-2994, I discovered MNG-3092 that >> was >> > > > > > contrary to the 2.0 design docs: >> > > > > > >> > > > > > http://jira.codehaus.org/browse/MNG-3092 >> > > > > > >> > > > > > Brett, Kenney and myself had a brief discussion on IRC about >> this: >> > > > > > Kenney says that the behaviour is theoretically correct (which >> it >> > > >> > > is), >> > > >> > > > > > although I feel it goes against the practical usage described >> in the >> > > > > > docs. The two main choices I can see are: >> > > > > > >> > > > > > 1) We stick to the design docs and disallow snapshots in ranges >> when >> > > > > > they aren't an explicit boundary, as per the MNG-3092 patch. >> > > > > > >> > > > > > 2) We reconsider the design docs and leave range resolution >> behaving >> > > > > > as it is, then use profiles to enable or disable snapshot >> > > >> > > repositories >> > > >> > > > > > at build time. >> > > > > > >> > > > > > Any thoughts? >> > > > > > >> > > > > > Mark >> > > >> > > --------------------------------------------------------------------- >> > > To unsubscribe, e-mail: dev-unsubscr...@maven.apache.org >> > > For additional commands, e-mail: dev-h...@maven.apache.org >> >> >> --------------------------------------------------------------------- >> To unsubscribe, e-mail: dev-unsubscr...@maven.apache.org >> For additional commands, e-mail: dev-h...@maven.apache.org >> >> >
