[MRESOLVER-480] Document latest changes (#429)

Those that may affect consumer projects.

Also, a small irrelevant (and harmless) change: remove the class `DependencyScopes` that got introduced in alpha-7, but got deprecated while working on alpha-8, where we made Resolver fully scope oblivious.

---

https://issues.apache.org/jira/browse/MRESOLVER-480

maven-resolver-util/src/main/java/org/eclipse/aether/util/artifact/JavaScopes.java

@@ -23,9 +23,7 @@
  *
  * @see org.eclipse.aether.graph.Dependency#getScope()
  *
- * @deprecated Definition and semantics of the scopes should be defined by consumer project. Resolver out-of-the-box
- * supported scopes are defined in {@link DependencyScopes} class. Resolver is oblivious about any other scopes and their
- * semantics.
+ * @deprecated Definition and semantics of the scopes should be defined by consumer project.
  */
 @Deprecated
 public final class JavaScopes {
@@ -34,7 +32,7 @@ public final class JavaScopes {
 
     public static final String PROVIDED = "provided";
 
-    public static final String SYSTEM = DependencyScopes.SYSTEM;
+    public static final String SYSTEM = "system";
 
     public static final String RUNTIME = "runtime";
 

maven-resolver-util/src/main/java/org/eclipse/aether/util/graph/transformer/JavaDependencyContextRefiner.java

@@ -23,7 +23,6 @@
 import org.eclipse.aether.collection.DependencyGraphTransformer;
 import org.eclipse.aether.graph.Dependency;
 import org.eclipse.aether.graph.DependencyNode;
-import org.eclipse.aether.util.artifact.DependencyScopes;
 import org.eclipse.aether.util.artifact.JavaScopes;
 
 import static java.util.Objects.requireNonNull;
@@ -35,9 +34,7 @@
  *
  * @see DependencyNode#getRequestContext()
  *
- * @deprecated This class belongs to consumer project. Resolver have no notion of scopes other than those defined
- * in {@link DependencyScopes} class, moreover it has no knowledge about scope transformation
- * of dependencies to build path scopes.
+ * @deprecated This class belongs to consumer project. Resolver should have no notion of scopes.
  */
 @Deprecated
 public final class JavaDependencyContextRefiner implements DependencyGraphTransformer {

maven-resolver-util/src/main/java/org/eclipse/aether/util/graph/transformer/JavaScopeDeriver.java

@@ -19,17 +19,14 @@
 package org.eclipse.aether.util.graph.transformer;
 
 import org.eclipse.aether.RepositoryException;
-import org.eclipse.aether.util.artifact.DependencyScopes;
 import org.eclipse.aether.util.artifact.JavaScopes;
 import org.eclipse.aether.util.graph.transformer.ConflictResolver.ScopeContext;
 import org.eclipse.aether.util.graph.transformer.ConflictResolver.ScopeDeriver;
 
 /**
  * A scope deriver for use with {@link ConflictResolver} that supports the scopes from {@link JavaScopes}.
  *
- * @deprecated This class belongs to consumer project. Resolver have no notion of scopes other than those defined
- * in {@link DependencyScopes} class, moreover it has no knowledge about scope transformation
- * of dependencies to build path scopes.
+ * @deprecated This class belongs to consumer project. Resolver should have no notion of scopes.
  */
 @Deprecated
 public final class JavaScopeDeriver extends ScopeDeriver {

maven-resolver-util/src/main/java/org/eclipse/aether/util/graph/transformer/JavaScopeSelector.java

@@ -23,7 +23,6 @@
 import java.util.Set;
 
 import org.eclipse.aether.RepositoryException;
-import org.eclipse.aether.util.artifact.DependencyScopes;
 import org.eclipse.aether.util.artifact.JavaScopes;
 import org.eclipse.aether.util.graph.transformer.ConflictResolver.ConflictContext;
 import org.eclipse.aether.util.graph.transformer.ConflictResolver.ConflictItem;
@@ -34,9 +33,7 @@
  * this selector picks the widest scope present among conflicting dependencies where e.g. "compile" is wider than
  * "runtime" which is wider than "test". If however a direct dependency is involved, its scope is selected.
  *
- * @deprecated This class belongs to consumer project. Resolver have no notion of scopes other than those defined
- * in {@link DependencyScopes} class, moreover it has no knowledge about scope transformation
- * of dependencies to build path scopes.
+ * @deprecated This class belongs to consumer project. Resolver should have no notion of scopes.
  */
 @Deprecated
 public final class JavaScopeSelector extends ScopeSelector {

src/site/markdown/upgrading-resolver.md

@@ -40,10 +40,31 @@ What changed on surface:
 * introduction of `RepositorySystem` new method `createSessionBuilder` that creates `SessionBuilder` instances.
 * deprecation of `DefaultRepositorySystemSession` default constructor, this constructor is actually the "Resolver 1.x way" of using sessions.
 
-Required changes in **client code managing Resolver 2.x**:
+Required changes in **consumer project code managing Resolver 2.x**:
 * do not use `DefaultRepositorySystemSession` default constructor anymore.
 * instead, use `RepositorySystem#createSessionBuilder` to create `SessionBuilder` and out of it `CloseableSession` instances.
 * handle sessions as resources: each created instance should be closed once finished their use.
 * session instances created by given `RepositorySystem` should be used only with that same instance.
 * to shallow-copy session instances (for alteration purposes) using existing `DefaultRepositorySystemSession` copy constructor is acceptable (this is what Mojos do).
 * to shallow-copy session instances but have new lifecycle as well, use `SessionBuilder#withRepositorySystemSession` on newly created builder instances.
+
+## Consumer Project Changes (if more needed)
+
+Maven Resolver 2.x now fully delegates multiple aspects to the consumer project, itself remaining "oblivious" about
+them. This was done to lessen (or better, fully remove) any overlap between the logic of the Resolver, and it's major
+consumer project: Maven. The following aspects are fully delegated to consumer projects:
+* Most of the `ArtifactProperties` is deprecated (sans two "core" ones: type and language), as it is really matter of the consumer project assign semantics to them.
+* The `ArtifactType` default implementation is deprecated, should be provided by consumer project instead, Resolver 2.x should not provide implementations for it.
+* Class path generation (in NodeListGenerator class variations in `org.eclipse.aether.util.graph.visitor` package) and class path filtering (in `DependencyFilterUtils`) is deprecated. It is the consumer app, based on own artifact properties, that can deduce how to build class path (or module path, or anything alike).
+* Dependency Scopes are fully removed. For Resolver, they were always "just labels". Resolver is now fully unaware of scopes (and for "system" artifacts has a dedicated handler exposed on session).
+
+For users of Maven Resolver Provider module, these changes will have clean migration path, as all the replacements for 
+items from the list above are present in `org.apache.maven:maven-resolver-provider` module. Still, for binary 
+compatibility, all affected classes are in fact left in place, but deprecated. Consumer projects should update 
+accordingly, and if they do use any deprecated classes from the resolver (affected modules are maven-resolver-api 
+and maven-resolver-util), they should switch to their counterparts, that are now present in maven-resolver-provider 
+module.
+
+Note: Resolver 2.x still fully supports "legacy" (Maven3-like) functionality, and if existing consumer
+code base adapts only the session related changes, consumer project can enjoy new features (like HTTP/2 transport),
+while keeping full compatibility, identical to Resolver 1.x release.