maven-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jon Harper <jon.harpe...@gmail.com>
Subject Re: Version ranges and snapshots
Date Mon, 23 Mar 2015 17:39:49 GMT
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.boutemy@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.boutemy@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.harper87@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-unsubscribe@maven.apache.org
> > > For additional commands, e-mail: dev-help@maven.apache.org
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> For additional commands, e-mail: dev-help@maven.apache.org
>
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message