gnodet commented on code in PR #2035:
URL: https://github.com/apache/maven-resolver/pull/2035#discussion_r3721314819
##########
src/site/markdown/common-misconceptions.md:
##########
@@ -96,12 +59,9 @@ Assume your project is using Google Guice, so you have
declared it as a dependen
</dependency>
```
-All fine and dandy. At the same time, you want to avoid any use of Guava. We
all know Guava is a direct dependency
-of Guice. This is fine, since as we know, the best practice is to declare all
dependencies your code compiles
-against. By not having Guava here, analysis tools will report if code touches
Guava as an "undeclared dependency".
+The model code does not directly use Guava. However, Guava is a direct
dependency of Guice.
Review Comment:
"The model code" is not standard Maven/Java terminology. In the Maven
ecosystem, "model" has a specific meaning (the POM model,
`org.apache.maven.model.Model`), so "model code" could be misread as referring
to the POM model code.
The original said "you want to avoid any use of Guava" — referring to the
project's production source code. Consider:
```suggestion
Your project code does not directly use Guava. However, Guava is a direct
dependency of Guice.
```
##########
src/site/markdown/common-misconceptions.md:
##########
@@ -18,75 +18,38 @@ specific language governing permissions and limitations
under the License.
-->
-Due to smooth transitions from Maven2 into Maven3 (and soon
-Maven4), and the fact that Maven2 plugins kept working with Maven3, maybe
-even without change, some misconceptions crept in
-as well. Despite the marvel of "compatibility", Maven3 resolution
-differs considerably from Maven2, and the sole reason is actual improvement
-in area of resolution. It became much more precise (and, due
-to that, lost some "bad" habits present in Maven2). Here, we will try to
-enumerate some of the most common misconceptions.
+Maven 2 plugins kept working with Maven 3 although Maven 3 resolution differs
from Maven 2 resolution. Resolution is now much more precise. Some old
behaviors from Maven 2 no longer exist. This page lists some of the most common
misconceptions.
-## Misconception No1: How Resolver Works
+## Misconception Number 1: How Resolver Works
(Simplified)
-The most typical use case for Resolver is to "resolve transitively"
-dependencies. Resolver, to achieve this, internally (but these are
-exposed via API as distinguished API calls as well) performs 3 steps:
-"collect", "transform" and "resolve".
-
-The "collect" step is first, where it builds the "dirty tree" (or dirty graph)
-of artifacts. It is important to remark, that in "collect" step, while
-the graph is being built, Maven uses only POMs. Hence, if collecting an
-Artifact that was never downloaded to your local repository, it will
-download **the POMs only**. Using POMs resolver is able to build current
-"node" of graph, but also figure outgoing vertices and adjacent nodes of
-current node and so on. Which dependency is chosen to continue with from
-the current node POM is decided by various criteria (configured).
-
-The "transform" step transforms the "dirty graph": this is where conflict
resolution
-happens. It is here when resolver applies various rules to resolve conflicting
-versions, conflicting scopes, and so on. Here, if "verbose tree" is asked for,
-conflict resolution does not remove graph nodes, merely marks the conflicts
-and the conflict "winner". Thus, "verbose tree" cannot be resolved.
-
-Finally, the "resolve" step runs, when the (transformed) graph node artifacts
-are being resolved, basically ensuring (and downloading if needed) their
-correspondent files (i.e. JAR files) are present in local repository.
-
-It is important to state, that in "collect" step happens the selection of nodes
-by various criteria, among other by the configured scope filters. And here we
-come to the notion of "runtime graph" vs "test graph".
-
-In resolver, maybe un-intuitively, the "scope filter" is usually used (but
does
-not have to, this is just how it IS used in Maven Core, probably for historical
-reasons) as "what should be omitted". The default session filter in Maven
-is set up as this:
+The most common use of Resolver is to resolve dependencies transitively.
Resolver performs three steps: "collect", "transform", and "resolve". Resolver
also exposes these steps as separate API calls.
+
+The "collect" step is first. During this step, Resolver builds the "dirty
tree" (or dirty graph) of artifacts. While it builds the graph, Maven only uses
POMs. If an artifact is not in your local repository, Maven downloads the POM
only. With the POM, Resolver builds the current node of the graph and finds its
outgoing vertices and adjacent nodes. The configured criteria decide which
dependency continues from the current node POM.
+
+The "transform" step transforms the "dirty graph". This is where conflict
resolution happens. Resolver applies rules to resolve conflicting versions and
conflicting scopes. If you ask for the "verbose tree", conflict resolution does
not remove graph nodes. It only marks the conflicts and the conflict "winner".
Therefore, the "verbose tree" cannot be resolved.
+
+Finally, in the "resolve" step, Resolver resolves the artifacts of the
transformed graph nodes. It ensures that the corresponding files (for example,
JAR files) are present in the local repository. It downloads them if needed.
+
+During the "collect" step, various criteria select the nodes. The configured
scope filters are among these criteria. This leads to the notion of the
"runtime graph" and the "test graph".
+
+The "scope filter" selects what to omit. This use of the filter is not
intuitive. Maven Core uses the filter this way. The default session filter in
Maven is set up as follows:
```
new ScopeDependencySelector("test", "provided")
```
-This means, that "current dependency node" dependencies in "test" and
"provided" scope
-will be simply omitted from the graph. In other words, this filter builds
-the "downstream runtime classpath" of supplied artifact (i.e. "what is needed
by the
-artifact at runtime when I depend on it").
-
-Note: these are NOT "Maven related" notions yet, there is nowhere Maven in
picture here,
-and these are not the classpath used by Compiler or Surefire plugins, merely
just
-a showcase how Resolver works.
+This filter omits the dependencies of the "current dependency node" that are
in the "test" and "provided" scope. In other words, this filter builds the
"downstream runtime classpath" of the supplied artifact. It shows what the
artifact needs at runtime when you depend on it.
+Note: These notions do not relate to Maven yet. Maven does not appear in this
example. This is not the classpath that the Compiler or Surefire plugins use.
It is only a showcase of how Resolver works.
-## Misconception No2: "Test graph" Is Superset Of "Runtime graph"
+## Misconception Number 2: "Test graph" is a Superset of the "Runtime graph"
-**Wrong**. As can be seen from above, for runtime graph we leave out "test"
scoped
-dependencies. It was true in Maven2, where test graph really was a superset of
runtime,
-but this does not stand anymore in Maven3. And this has interesting
consequences. Let me show an example:
+**Wrong**. For the runtime graph, Resolver omits the "test" scoped
dependencies. This has interesting consequences. The example below shows this.
Review Comment:
The original stated: _"It was true in Maven2, where test graph really was a
superset of runtime, but this does not stand anymore in Maven3."_
This historical context is important on a page titled "Common
Misconceptions" — it explains *why* people hold this belief (because it was
actually true in Maven 2). Without it, the section says "Wrong" but doesn't
explain the origin. Consider restoring it:
```suggestion
**Wrong**. In Maven 2, the test graph was a superset of the runtime graph.
This is no longer true in Maven 3. For the runtime graph, Resolver omits the
"test" scoped dependencies. This has interesting consequences. The example
below shows this.
```
##########
src/site/markdown/common-misconceptions.md:
##########
@@ -96,12 +59,9 @@ Assume your project is using Google Guice, so you have
declared it as a dependen
</dependency>
```
-All fine and dandy. At the same time, you want to avoid any use of Guava. We
all know Guava is a direct dependency
-of Guice. This is fine, since as we know, the best practice is to declare all
dependencies your code compiles
-against. By not having Guava here, analysis tools will report if code touches
Guava as an "undeclared dependency".
+The model code does not directly use Guava. However, Guava is a direct
dependency of Guice.
Review Comment:
Nit: trailing whitespace at the end of this line (after "Guice.").
--
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]
