You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@maven.apache.org by Jon Harper <jo...@gmail.com> on 2017/02/11 17:19:33 UTC
Re: Version ranges and snapshots
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 <jo...@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 <he...@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 <he...@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 <jo...@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
>>
>>
>