[
https://issues.apache.org/jira/browse/MRESOLVER-466?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17809930#comment-17809930
]
ASF GitHub Bot commented on MRESOLVER-466:
------------------------------------------
cstamas commented on code in PR #409:
URL: https://github.com/apache/maven-resolver/pull/409#discussion_r1463215080
##########
src/site/markdown/common-misconceptions.md:
##########
@@ -0,0 +1,204 @@
+# 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
+
+ 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.
+-->
+
+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, there were some misconceptions crept in
+as well. Despite the marvel of "compatibility", Maven3 resolution
+differs quite much from Maven2, and the sole reason is actual improvement
+in area of resolution, it became much more precise (and, due
+that lost some "bad" habits present in Maven2). Here, we will try to
+enumerate some of the most common misconceptions.
+
+## Misconception No1: 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" (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 classpath" vs "test classpath".
+
+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:
+
+```
+ 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").
+
+With selector like this:
+
+```
+ new ScopeDependencySelector("provided")
+```
+
+the "downstream dependency test classpath" would be built. Aside of giving
example,
+this selector is actually never used, as "test classpath" makes sense only in
the
+scope of "current project", but not for "downstream dependant projects".
+
+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.
+
+
+## Misconception No2: "Test classpath" Is Superset of "Runtime classpath"
Review Comment:
```suggestion
## Misconception No2: "Test classpath" Is Superset Of "Runtime classpath"
```
> Extend site documentation
> -------------------------
>
> Key: MRESOLVER-466
> URL: https://issues.apache.org/jira/browse/MRESOLVER-466
> Project: Maven Resolver
> Issue Type: Task
> Components: Resolver
> Reporter: Tamas Cservenak
> Assignee: Tamas Cservenak
> Priority: Major
> Fix For: 2.0.0, 2.0.0-alpha-7
>
>
> Add more details to site (RRF, Checksums, etc).
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
