This is an automated email from the ASF dual-hosted git repository.

slachiewicz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-site.git


The following commit(s) were added to refs/heads/master by this push:
     new c7b94a6a Add a page on common dependency resolution misconceptions
c7b94a6a is described below

commit c7b94a6a8e5b1c2786bfbd5f383e1b56659f18a8
Author: Sylwester Lachiewicz <[email protected]>
AuthorDate: Sat Oct 31 20:10:59 2026 +0000

    Add a page on common dependency resolution misconceptions
---
 content/filtered-resources/.htaccess               |   2 +
 .../dependency-resolution-misconceptions.md        | 142 +++++++++++++++++++++
 content/markdown/repositories/index.md             |   1 +
 content/site.xml                                   |   1 +
 4 files changed, 146 insertions(+)

diff --git a/content/filtered-resources/.htaccess 
b/content/filtered-resources/.htaccess
index e184e769..643a334f 100644
--- a/content/filtered-resources/.htaccess
+++ b/content/filtered-resources/.htaccess
@@ -118,6 +118,8 @@ RedirectMatch ^/archives/maven-parent-LATEST(.*)$ 
/pom-archives/maven-LATEST$1
 RedirectMatch ^/archives/(maven-.*-skin)-LATEST(.*)$ 
/skins-archives/$1-LATEST$2
 RedirectMatch ^/archives/(maven-.*-extension)-LATEST(.*)$ 
/extensions-archives/$1-LATEST$2
 
+Redirect Permanent /resolver/common-misconceptions.html 
/repositories/dependency-resolution-misconceptions.html
+
 # used in ATR announce templates - 
https://maven.apache.org/release-notes/{{PROJECT_KEY}}/{{VERSION}}
 # redirect to the GitHub release page, the Git tag is usually 
<artifactId>-<version>
 
diff --git 
a/content/markdown/repositories/dependency-resolution-misconceptions.md 
b/content/markdown/repositories/dependency-resolution-misconceptions.md
new file mode 100644
index 00000000..98797bf7
--- /dev/null
+++ b/content/markdown/repositories/dependency-resolution-misconceptions.md
@@ -0,0 +1,142 @@
+# Common Misconceptions About Dependency Resolution
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+Maven 2 plugins kept working with Maven 3, although [Maven 
Resolver](/resolver/) resolves dependencies differently from Maven 2: 
resolution is now much more precise, and some Maven 2 behaviors no longer 
exist. This page lists the most common misconceptions.
+
+## Misconception Number 1: How Resolver Works
+
+(Simplified)
+
+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 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 Number 2: "Test graph" is a Superset of the "Runtime graph"
+
+**Wrong**. For the runtime graph, Resolver omits the "test" scoped 
dependencies. This has interesting consequences. The example below shows this.
+
+The example below uses Guice and Guava.
+Your project uses Google Guice. You have declared Guice as a dependency:
+
+```
+      <dependency>
+        <groupId>com.google.inject</groupId>
+        <artifactId>guice</artifactId>
+        <version>${guiceVersion}</version>
+      </dependency>
+```
+
+The src/main code does not directly use Guava. However, Guava is a direct 
dependency of Guice.
+Your unit tests do need Guava so you add Guava as a test-scoped dependency. 
The POM now looks like this:
+
+
+```
+      <dependency>
+        <groupId>com.google.inject</groupId>
+        <artifactId>guice</artifactId>
+        <version>${guiceVersion}</version>
+      </dependency>
+      <dependency>
+        <groupId>com.google.guava</groupId>
+        <artifactId>guava</artifactId>
+        <version>${guavaVersion}</version>
+        <scope>test</scope>
+      </dependency>
+```
+
+The `dependency:tree` plugin for this project outputs this verbose tree:
+
+```
+[INFO] --- dependency:3.6.1:tree (default-cli) @ DEMO-PROJECT ---
+[INFO] DEMO-PROJECT
+[INFO] +- com.google.inject:guice:jar:6.0.0:compile
+[INFO] |  +- javax.inject:javax.inject:jar:1:compile
+[INFO] |  +- jakarta.inject:jakarta.inject-api:jar:2.0.1:compile
+[INFO] |  +- aopalliance:aopalliance:jar:1.0:compile
+[INFO] |  \- (com.google.guava:guava:jar:31.0.1-jre:compile - omitted for 
duplicate)
+[INFO] \- com.google.guava:guava:jar:31.0.1-jre:test (scope not updated to 
compile)
+[INFO]    +- com.google.guava:failureaccess:jar:1.0.1:test
+[INFO]    +- 
com.google.guava:listenablefuture:jar:9999.0-empty-to-avoid-conflict-with-guava:test
+[INFO]    +- com.google.code.findbugs:jsr305:jar:3.0.2:test
+[INFO]    +- org.checkerframework:checker-qual:jar:3.12.0:test
+[INFO]    +- com.google.errorprone:error_prone_annotations:jar:2.7.1:test
+[INFO]    \- com.google.j2objc:j2objc-annotations:jar:1.3:test
+```
+
+This is the "test graph" of the project. It contains a conflict indicated by 
the remarks "omitted for duplicate" and "scope not updated to compile" next to 
the Guava nodes.
+
+This setup has these results:
+
+* When you compile, Guava is not on the compile classpath. You cannot touch it 
by mistake.
+* When test-compile and test-execute run, Guava is present on the classpath, 
as expected.
+
+What happens when someone consumes this library downstream? Nothing. 
Everything works as expected.
+
+When a downstream project declares a dependency on your project, it gets this 
graph from the node of your library:
+
+```
+[INFO] --- dependency:3.6.1:tree (default-cli) @ DOWNSTREAM-PROJECT ---
+[INFO] DOWNSTREAM-PROJECT
+[INFO] \- DEMO-PROJECT:compile
+[INFO]    \- com.google.inject:guice:jar:6.0.0:compile
+[INFO]       +- javax.inject:javax.inject:jar:1:compile
+[INFO]       +- jakarta.inject:jakarta.inject-api:jar:2.0.1:compile
+[INFO]       +- aopalliance:aopalliance:jar:1.0:compile
+[INFO]       \- com.google.guava:guava:jar:31.0.1-jre:compile
+[INFO]          +- com.google.guava:failureaccess:jar:1.0.1:compile
+[INFO]          +- 
com.google.guava:listenablefuture:jar:9999.0-empty-to-avoid-conflict-with-guava:compile
+[INFO]          +- com.google.code.findbugs:jsr305:jar:3.0.2:compile
+[INFO]          +- org.checkerframework:checker-qual:jar:3.12.0:compile
+[INFO]          +- 
com.google.errorprone:error_prone_annotations:jar:2.7.1:compile
+[INFO]          \- com.google.j2objc:j2objc-annotations:jar:1.3:compile
+```
+
+What happens here? The section "How Resolver Works" above explains this. For 
the "runtime graph" of the dependency, Resolver does not consider the "test" 
and "provided" scopes of the dependency artifact. Resolver omits them 
completely. It does not skip them. They do not exist in the graph.
+
+Therefore, no conflict happens. Resolver omits the "test" Guava during the 
"collect" step. Everything goes as expected.
+
+### Important Consequences
+
+One consequence is not so obvious. It involves the `maven-assembly-plugin`. 
You want to assemble the "runtime" dependencies of the module.
+
+If you assemble from within the project, for example in the package phase, the 
packaging will be incomplete. Guava will be missing. If you assemble from 
outside the project, the assembly will contain Guava. This includes assembly 
from a subsequent module of the build or from a downstream dependency.
+
+This behavior was tracked as a [Maven Assembly plugin 
bug](https://issues.apache.org/jira/browse/MASSEMBLY-1008), which was fixed in 
Assembly 3.7.0. The related 
[MRESOLVER-391](https://issues.apache.org/jira/browse/MRESOLVER-391) issue 
remains useful background, but it does not describe an unresolved bug in 
current Assembly releases. The Maven Assembly plugin previously considered the 
"test graph" of the project and then "cherry-picked" the runtime-scoped nodes 
from that graph.
+
+You must build different graphs for the "runtime" and "test" classpath. The 
Assembly plugin is a Mojo. It requests the "test graph". Then it reads the 
configuration (the assembly descriptor). It learns the required scopes at this 
point. Then it "filters" the resolved "test graph" for the runtime scopes.
+
+This is wrong, because Guava is in the test scope. The plugin must read the 
configuration first. Then it must ask Resolver for the "runtime graph". Then it 
must filter the graph. This problem does not exist with `maven-war-plugin`. The 
"war" Mojo asks for the "compile+runtime" scope. The WAR case is much simpler 
than the Assembly use case. The WAR plugin always packages the same scope.
diff --git a/content/markdown/repositories/index.md 
b/content/markdown/repositories/index.md
index ffa8cb65..78631798 100644
--- a/content/markdown/repositories/index.md
+++ b/content/markdown/repositories/index.md
@@ -55,3 +55,4 @@ Sections:
 * [Layout](layout.md)
 * [Local Repositories](local.md)
 * [Remote Repositories](remote.md)
+* [Dependency Resolution 
Misconceptions](dependency-resolution-misconceptions.md)
diff --git a/content/site.xml b/content/site.xml
index 406216d8..f2734d96 100644
--- a/content/site.xml
+++ b/content/site.xml
@@ -187,6 +187,7 @@ under the License.
         <item name="Maven Layout" href="/repositories/layout.html"/>
         <item name="Maven Local Repository" href="/repositories/local.html"/>
         <item name="Maven Remote Repositories" 
href="/repositories/remote.html"/>
+        <item name="Dependency Resolution Misconceptions" 
href="/repositories/dependency-resolution-misconceptions.html"/>
       </item>
       <item name="Plugin Development" href="/plugin-developers/index.html" 
collapse="true">
         <item name="Introduction" 
href="/guides/introduction/introduction-to-plugins.html"/>

Reply via email to