[jira] [Commented] (MRESOLVER-466) Extend site documentation

["ASF GitHub Bot (Jira)" <ji...@apache.org>]

    [ 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)