You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by el...@apache.org on 2026/07/23 15:27:03 UTC
(maven-resolver) 01/01: Fix documentation issues across site docs
This is an automated email from the ASF dual-hosted git repository.
elharo pushed a commit to branch fix-docs-issues
in repository https://gitbox.apache.org/repos/asf/maven-resolver.git
commit 167e1de13bcea89f78f1b2846da138f489d4c4a7
Author: opencode <op...@example.com>
AuthorDate: Thu Jul 23 15:26:02 2026 +0000
Fix documentation issues across site docs
---
src/site/markdown/about-checksums.md | 8 ++++----
src/site/markdown/api-compatibility.md | 14 ++++++--------
src/site/markdown/common-misconceptions.md | 10 +++++-----
src/site/markdown/creating-a-repository-system-session.md | 6 +++---
src/site/markdown/deployment.md | 4 ++--
src/site/markdown/how-resolver-works.md | 6 +++---
src/site/markdown/local-repository.md | 8 ++++----
src/site/markdown/remote-repository-filtering.md | 6 +++---
src/site/markdown/repository-key-function.md | 2 +-
src/site/markdown/third-party-integrations.md | 2 +-
src/site/markdown/transporter-known-issues.md | 2 +-
src/site/markdown/upgrading-resolver.md | 4 ++--
src/site/markdown/what-is-resolver.md | 4 ++--
src/site/xdoc/index.xml | 2 +-
14 files changed, 38 insertions(+), 40 deletions(-)
diff --git a/src/site/markdown/about-checksums.md b/src/site/markdown/about-checksums.md
index aec7808ce..dbb0f74d8 100644
--- a/src/site/markdown/about-checksums.md
+++ b/src/site/markdown/about-checksums.md
@@ -23,7 +23,7 @@ metadata. Checksums are usually laid out in repositories next to the file in que
extension telling the checksum algorithm that produced the given checksum file content. Currently,
most Maven repositories contain SHA-1 and MD5 checksums by default (they are produced by Resolver by default).
-Historically, Maven Resolver used `java.security.MessageDigest` to implement checksums. So to say, secure one-way
+Historically, Maven Resolver used `java.security.MessageDigest` to implement checksums. So to speak, secure one-way
hashes provided by Java Cryptography Architecture were (mis)used to implement checksums for transport integrity
validation. There is no misunderstanding here, secure hashes MAY be used as checksums, as there is quite some
overlap between checksums and hashes in general. But this simplicity comes at a price: cryptographically safe
@@ -41,12 +41,12 @@ validation" or "error detection" (aka "bit-rot detection").
## Checksum Algorithms SPI
-From a technical perspective, the above written facts infer following consequences: as checksum algorithms are exposed
+From a technical perspective, the above written facts imply following consequences: as checksum algorithms are exposed
to the user, so one can set them via configuration, users are not prevented to ask for SHA-256 or even SHA-512, even if
-these algorithms are not part of standard Maven process. Moreover, nothing prevent users (integrating
+these algorithms are not part of standard Maven process. Moreover, nothing prevents users (integrating
Maven Resolver) registering with Java an alternate Java Cryptography Provider and use even broader (or exotic) set
of message digests for checksums. While this is not wrong or even mistake in any case, we do consider this as
-wrong use case. The notion of transport validation and secure hashes are being constantly mixed up due historical
+wrong use case. The notion of transport validation and secure hashes are being constantly mixed up due to historical
reasons explained above.
Hence, Maven Resolver team decided to make supported set of checksums more controlled. Instead of directly exposing
diff --git a/src/site/markdown/api-compatibility.md b/src/site/markdown/api-compatibility.md
index 14290f1d3..c3358f207 100644
--- a/src/site/markdown/api-compatibility.md
+++ b/src/site/markdown/api-compatibility.md
@@ -70,11 +70,9 @@ changes using version number. We use "major.minor.patch" versioning on resolver
semantics:
* On major version change, one should NOT expect any backward compatibility.
-* On minor version change, we TRY to keep backward compatibility for those "exposed" 3 modules:
- API, SPI and Util. Still, there are examples when we failed to do so, usually driven by new
- features.
-* On minor version change, we ENSURE backward compatibility for those "exposed" 3 modules: API,
- SPI and Util.
+ * On minor version change, we ENSURE backward compatibility for those "exposed" 3 modules: API,
+ SPI and Util. Still, there are examples when we failed to do so, usually driven by new
+ features.
In any of three version changes above, in areas where we do not offer guarantees, everything
can happen.
@@ -88,9 +86,9 @@ above.
## Inside of Maven
-Historically, Maven 3.1 (as Maven 3.0 used resolver from different package) provided API, SPI
-and Impl from its own embedded resolver, while Util, Connector, if some plugin or extension
-depended on those, was resolved. This caused that a plugin may work with different versions
+Historically, Maven 3.1 (as Maven 3.0 used a resolver from a different package) provided API, SPI
+and Impl from its own embedded resolver, while Util and Connector, if some plugin or extension
+depended on them, were resolved separately. This caused that a plugin may work with different versions
of API, SPI, Impl or Connector. Given Resolver had API "frozen" for too long time, this was essentially
not a problem, but still weird.
diff --git a/src/site/markdown/common-misconceptions.md b/src/site/markdown/common-misconceptions.md
index ea2d453d0..d6c707f0f 100644
--- a/src/site/markdown/common-misconceptions.md
+++ b/src/site/markdown/common-misconceptions.md
@@ -22,9 +22,9 @@ 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
+differs considerably 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
+to 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
@@ -36,7 +36,7 @@ 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)
+The "collect" step is first, where it builds the "dirty tree" (or 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
@@ -81,8 +81,8 @@ a showcase how Resolver works.
## Misconception No2: "Test graph" Is Superset Of "Runtime graph"
**Wrong**. As can be seen from above, for runtime graph we leave out "test" scoped
-dependencies. It was true in Maven2, where test graph really was superset of runtime,
-this does not stand anymore in Maven3. And this have interesting consequences. Let me show an example:
+dependencies. It was true in Maven2, where test graph really was a superset of runtime,
+but this does not stand anymore in Maven3. And this have interesting consequences. Let me show an example:
(Note: very same scenario, as explained below for Guice+Guava would work for Jackson Databind+Core, etc.)
diff --git a/src/site/markdown/creating-a-repository-system-session.md b/src/site/markdown/creating-a-repository-system-session.md
index 8bf604c8f..2a97d7524 100644
--- a/src/site/markdown/creating-a-repository-system-session.md
+++ b/src/site/markdown/creating-a-repository-system-session.md
@@ -35,12 +35,12 @@ import org.eclipse.aether.supplier.RepositorySystemSupplier;
...
private static RepositorySystemSession newSession( RepositorySystem system )
{
- RepositorySystemSession.SessionBuilder sessionBuilder = SessionBuilderSupplier.get();
+ RepositorySystemSession.SessionBuilder sessionBuilder = system.createSessionBuilder();
LocalRepository localRepo = new LocalRepository( "target/local-repo" );
- sessionBuilder.setLocalRepositoryManager( system.newLocalRepositoryManager( session, localRepo ) );
+ sessionBuilder.setLocalRepositoryManager( system.newLocalRepositoryManager( sessionBuilder, localRepo ) );
- return session.build();
+ return sessionBuilder.build();
}
```
diff --git a/src/site/markdown/deployment.md b/src/site/markdown/deployment.md
index b7e85e996..49b9f8c87 100644
--- a/src/site/markdown/deployment.md
+++ b/src/site/markdown/deployment.md
@@ -22,9 +22,9 @@ Deploying artifacts and related metadata to a (remote) repository can be achieve
The most prominent consumer of this API is probably [maven-deploy-plugin](https://maven.apache.org/plugins/maven-deploy-plugin/).
-# Repository Connector
+## Repository Connector
-The default repository connector implementation at [`BasicRepositoryConnectorFactory`](https://github.com/apache/maven-resolver/blob/master/maven-resolver-connector-basic/src/main/java/org/eclipse/aether/connector/basic/BasicRepositoryConnector.java) uses a `RepositoryLayout` to calculate the URL and a `Transporter` to achieve the actual upload/write of artifacts/metadata.
+The default repository connector implementation at [`BasicRepositoryConnector`](https://github.com/apache/maven-resolver/blob/master/maven-resolver-connector-basic/src/main/java/org/eclipse/aether/connector/basic/BasicRepositoryConnector.java) uses a `RepositoryLayout` to calculate the URL and a `Transporter` to achieve the actual upload/write of artifacts/metadata.
## Repository Layout
diff --git a/src/site/markdown/how-resolver-works.md b/src/site/markdown/how-resolver-works.md
index 206d9bce9..7cebc8ddc 100644
--- a/src/site/markdown/how-resolver-works.md
+++ b/src/site/markdown/how-resolver-works.md
@@ -46,7 +46,7 @@ The term "resolving" is a bit overloaded, but in general it involves following s
We call an artifact "resolvable" if it can be resolved from any available (local or remote) repository. To make an artifact
"resolvable" from the local repository, one needs to "install" it. To make an artifact "resolvable" from a remote repository,
-one needs to "deploy" it (this is an over-simplification; publishing is new term, but it also involves deploy step).
+one needs to "deploy" it (this is an over-simplification; publishing is a new term, but it also involves deploy step).
Furthermore, there are extension points like `WorkspaceReader` that can make artifacts resolvable
without installing or deploying them, but that is an integration detail (like Maven does by exposing reactor projects).
@@ -61,7 +61,7 @@ The BF collector is now the default, as it offers better performance.
One very important thing, that is constantly misunderstood, is what information is used during graph collection.
Only certain parts of the effective model are used, not the whole POM.
-If I am allowed to overly simplify, only the following aspects of the effective model are used during graph collection:
+If I may oversimplify, only the following aspects of the effective model are used during graph collection:
* `project/dependencies` as direct dependencies on given node
* `project/dependencyManagement/dependencies` for **subsequent** dependency management on given node
* `project/repositories` for **subsequent** repositories to be used on given node
@@ -114,7 +114,7 @@ In general, the steps "dependency graph collection" and "conflict resolution" ar
The "flattening" and "artifact resolving" are also usually done together, and we use for those the term "artifact resolution".
To make the story more confusing, when all the steps are performed together is also called "dependency resolution".
The Resolver API reflects this terminology and offers methods doing collection, resolution or both.
-*
+
* The method `CollectResult collectDependencies(RepositorySystemSession session, CollectRequest request)` performs only the collection step,
as its name suggests. Hence, only the steps "collection" and "conflict resolution" are performed.
* Method `List<ArtifactResult> resolveArtifacts(RepositorySystemSession session, Collection<? extends ArtifactRequest> requests)`
diff --git a/src/site/markdown/local-repository.md b/src/site/markdown/local-repository.md
index 4399eb66e..36eaf6496 100644
--- a/src/site/markdown/local-repository.md
+++ b/src/site/markdown/local-repository.md
@@ -102,7 +102,7 @@ can happen based even on origin repository (if split by remote repository
was enabled beforehand).
Example configuration with split by remote repository:
-```java
+```sh
$ mvn ... -Daether.enhancedLocalRepository.split \
-Daether.enhancedLocalRepository.splitRemoteRepository
```
@@ -124,9 +124,9 @@ coexist in local repository. They will land in different places, due different
prefixes.
Example configuration for branches:
-```java
+```sh
$ mvn ... -Daether.enhancedLocalRepository.split \
- -Daether.enhancedLocalRepository.localPrefix=maven-resolver/mresolver-253
+ -Daether.enhancedLocalRepository.localPrefix=maven-resolver/mresolver-253 \
-Daether.enhancedLocalRepository.splitRemoteRepository
```
@@ -197,7 +197,7 @@ Each artifact/metadata which cannot be resolved leads to an error either classif
1. *not found* error or
2. (any) *other* error (for authentication issues, timeouts etc.)
-The caching behavior for both error types can be be configured programmatically via `org.eclipse.aether.DefaultRepositorySystemSession.setResolutionErrorPolicy(...)`.
+The caching behavior for both error types can be configured programmatically via `org.eclipse.aether.DefaultRepositorySystemSession.setResolutionErrorPolicy(...)`.
In case caching is enabled for any of the two classifications a Java Properties file is created/updated (with the same filename as the cached artifact in the success case would get but with the additional suffix `.lastUpdated`) in the local repository. Within that file the key `<canonical-remote-url>.error` is updated/added. Its value either contains the error message (for type 2 resolver errors) or is empty (for type 1 resolver errors).
diff --git a/src/site/markdown/remote-repository-filtering.md b/src/site/markdown/remote-repository-filtering.md
index 98c73b364..d22c511c3 100644
--- a/src/site/markdown/remote-repository-filtering.md
+++ b/src/site/markdown/remote-repository-filtering.md
@@ -43,7 +43,7 @@ and artifacts are resolved using a loop and a "first found wins" strategy. This
### What It Is
You can instruct Maven which repository can contain which artifacts. Instead of "ordered loop" searching
-for artifacts in remote repositories, Maven can query a repository that has the artifact first,.
+for artifacts in remote repositories, Maven can query a repository that has the artifact first.
With RRF, the Maven build does not slow down when new remote repositories are added, and does not leak
build information unnecessarily.
@@ -193,7 +193,7 @@ applied. Ideally, user should keep files sorted or handle them in a way one can
To make RRF filters operate, as they are by default enabled, you have to make sure that:
* prefix file can be discovered (if not for any reason, you may provide alternate input for it)
-* groupId is procided.
+* groupId is provided.
As said above, enabled filters does not make them active (participate in filtering): if a given remote repository does not have
any input available, the filter pulls out from "voting" (does not participate in filtering, will abstain
@@ -217,6 +217,6 @@ This leads to the following "constraints":
Users of certain Maven Repository Managers (MRM) reported issues with filtering, breaking their builds. Usually the issue involves grouped/virtual repositories where MRM leaks random resources from member repositories, like the `prefixes.txt` is. Naturally, as MRM leaks one member prefixes file, and Maven is "tricked" into belief it got proper prefixes file from remote repository, builds will fail with message like **Prefix `$PREFIX` NOT allowed from `$SERVER_ID`** (where `$PREFIX` is so [...]
-In this case, user should disable prefix discovery by using `-Daether.remoteRepositoryFilter.prefixes.resolvePrefixFiles=false` user property to prevent Maven attempting to resolve prefixes file from such broken MRMs.
+In this case, user should disable prefix discovery by using `-Daether.remoteRepositoryFilter.prefixes.resolvePrefixFiles=false` user property to prevent Maven from attempting to resolve the prefixes file from such broken MRMs.
Since 2.0.21, Resolver protects itself against this failure mode: when an auto-discovered prefixes file denies a path, the very first denial per remote repository is verified against the remote repository itself using a lightweight existence check. If the repository actually serves the denied path, the auto-discovered prefixes file is provably wrong; a warning naming the repository is emitted (report it to the repository administrator) and the file is ignored for the rest of the session, [...]
diff --git a/src/site/markdown/repository-key-function.md b/src/site/markdown/repository-key-function.md
index 250df5e28..3226f5074 100644
--- a/src/site/markdown/repository-key-function.md
+++ b/src/site/markdown/repository-key-function.md
@@ -64,7 +64,7 @@ Furthermore, repository key function (possibly different one) is used in two com
* Trusted Checksums Source
* Remote Repository Filter
-In these cases, the repository key function only role is to provide "file system friendly" path segments based on
+In these cases, the repository key function's only role is to provide "file system friendly" path segments based on
`RemoteRepository` instances.
**Important implication:** When Resolver/Maven is reconfigured to use alternative repository key function, it is
diff --git a/src/site/markdown/third-party-integrations.md b/src/site/markdown/third-party-integrations.md
index c0807c42f..c52eca5a4 100644
--- a/src/site/markdown/third-party-integrations.md
+++ b/src/site/markdown/third-party-integrations.md
@@ -21,7 +21,7 @@ from the beginning. Back when SL was implemented, the DI container in use with R
Maven was the Plexus DI container, that had its own limitations: no constructor injection
among others. Hence, the two was somewhat aligned with each other. Today, with Sisu DI,
this is not true anymore: we want to use constructor injection for components, but
-SL is always getting into our way forcing us to always add default constructor to components.
+SL is always getting in our way forcing us to always add default constructor to components.
Hence, decision was made, and SL was deprecated while ago, and is about to be
dropped in Resolver 2.0.0 release.
diff --git a/src/site/markdown/transporter-known-issues.md b/src/site/markdown/transporter-known-issues.md
index 638347ea8..f98cda65a 100644
--- a/src/site/markdown/transporter-known-issues.md
+++ b/src/site/markdown/transporter-known-issues.md
@@ -22,7 +22,7 @@ This page lists known issues related to various transporters.
## The `jdk` (Java HttpClient) Transporter
-Given this transporter uses the Java HttpClient (available since Java 11), it is the user's best interest
+Given this transporter uses the Java HttpClient (available since Java 11), it is in the user's best interest
to use latest patch version of Java, as HttpClient is getting bugfixes regularly.
### Known issues:
diff --git a/src/site/markdown/upgrading-resolver.md b/src/site/markdown/upgrading-resolver.md
index db403f867..d0ee8fbfe 100644
--- a/src/site/markdown/upgrading-resolver.md
+++ b/src/site/markdown/upgrading-resolver.md
@@ -51,9 +51,9 @@ Required changes in **consumer project code managing Resolver 2.x**:
## 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
+them. This was done to lessen (or better, fully remove) any overlap between the logic of the Resolver, and its 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.
+* Most of the `ArtifactProperties` is deprecated (except two "core" ones: type and language), as it is really a matter of the consumer project to 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).
diff --git a/src/site/markdown/what-is-resolver.md b/src/site/markdown/what-is-resolver.md
index 9640ad14d..8f1fe08ea 100644
--- a/src/site/markdown/what-is-resolver.md
+++ b/src/site/markdown/what-is-resolver.md
@@ -59,6 +59,6 @@ makes Resolver "minimally complete" (contains required component implementations
and introduces required models for Maven repositories). But this is still
just "basic resolver functionality". Next functionality
level is add "Maven environment awareness" (like honoring settings.xml and alike). This
-can be achieved by using libraries like [MIMA](https://github.com/maveniverse/mima)
-is. And finally, Maven (that incorporates Resolver) offers full experience (while
+can be achieved by using libraries like [MIMA](https://github.com/maveniverse/mima).
+And finally, Maven (that incorporates Resolver) offers full experience (while
embedding Maven is really not trivial).
diff --git a/src/site/xdoc/index.xml b/src/site/xdoc/index.xml
index 32bc0bb94..07f2d0b8b 100644
--- a/src/site/xdoc/index.xml
+++ b/src/site/xdoc/index.xml
@@ -36,7 +36,7 @@
</p>
<p>
- <img src="images/maven-resolver-deps.png" width="792" height="441" border="0" usemap="#Maven_Resolver_dependencies" />
+ <img src="images/maven-resolver-deps.png" width="792" height="441" border="0" usemap="#Maven_Resolver_dependencies" alt="" />
<map name="Maven_Resolver_dependencies">
<area shape="rect" coords="285,405,348,441" href="./maven-resolver-api/" />
<area shape="rect" coords="286,335,349,370" href="./maven-resolver-spi/" />