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 <[email protected]>
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 <[email protected]>
> 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: [email protected]
> For additional commands, e-mail: [email protected]
>
>
