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-resolver.git


The following commit(s) were added to refs/heads/master by this push:
     new 9a834503c Move the common misconceptions page to maven.apache.org
9a834503c is described below

commit 9a834503cc3939ce9a70444fdc28fcde719f6088
Author: Sylwester Lachiewicz <[email protected]>
AuthorDate: Sat Oct 31 20:13:22 2026 +0000

    Move the common misconceptions page to maven.apache.org
---
 src/site/markdown/common-misconceptions.md | 141 -----------------------------
 src/site/markdown/how-resolver-works.md    |   2 +-
 src/site/site.xml                          |   1 -
 3 files changed, 1 insertion(+), 143 deletions(-)

diff --git a/src/site/markdown/common-misconceptions.md 
b/src/site/markdown/common-misconceptions.md
deleted file mode 100644
index 4b55a317e..000000000
--- a/src/site/markdown/common-misconceptions.md
+++ /dev/null
@@ -1,141 +0,0 @@
-# Common Misconceptions
-<!--
-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
-
-    https://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 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 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/src/site/markdown/how-resolver-works.md 
b/src/site/markdown/how-resolver-works.md
index 0e98af48d..f3a479fd6 100644
--- a/src/site/markdown/how-resolver-works.md
+++ b/src/site/markdown/how-resolver-works.md
@@ -104,7 +104,7 @@ for its own pom.xml. It does not affect the versions of the 
dependencies of the
 In Resolver 2.x, `project/dependencyManagement` does define versions of 
dependencies
 for the transitive dependencies.
 
-See also [common misconceptions](common-misconceptions.html).
+See also [common 
misconceptions](https://maven.apache.org/repositories/dependency-resolution-misconceptions.html).
 
 ### Conflict Resolution
 
diff --git a/src/site/site.xml b/src/site/site.xml
index c84643a11..21e1289fd 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -43,7 +43,6 @@ under the License.
       <item name="Dependency Graph" href="dependency-graph.html"/>
       <item name="Creating a RepositorySystemSession" 
href="creating-a-repository-system-session.html"/>
       <item name="Resolving Dependencies" href="resolving-dependencies.html"/>
-      <item name="Common Misconceptions" href="common-misconceptions.html"/>
       <item name="Artifact Deployment" href="deployment.html"/>
       <item name="How Resolver Works" href="how-resolver-works.html"/>
       <item name="Transporter Known Issues" 
href="transporter-known-issues.html"/>

Reply via email to