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"/>