This is an automated email from the ASF dual-hosted git repository.
gnodet pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven.git
The following commit(s) were added to refs/heads/master by this push:
new be580f219a [MNG-8752] Improve Javadoc on DependencyScope (#13267)
be580f219a is described below
commit be580f219a4f035ffbfe955823c38f67be741ffc
Author: HARSHA B <[email protected]>
AuthorDate: Fri Nov 6 22:13:11 2026 +0530
[MNG-8752] Improve Javadoc on DependencyScope (#13267)
* MNG-8725: Support max thread configuration
* MNG-8752: Clarify provided dependency transitivity
* MNG-8752: Expand dependency scope Javadocs
* Fix javadoc accuracy in DependencyScope
* Fix license declaration in PR description
---------
Co-authored-by: Guillaume Nodet <[email protected]>
---
.../java/org/apache/maven/api/DependencyScope.java | 47 ++++++++++++++++++++--
1 file changed, 43 insertions(+), 4 deletions(-)
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/DependencyScope.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/DependencyScope.java
index 311f1ec39e..aaf8912eaa 100644
--- a/api/maven-api-core/src/main/java/org/apache/maven/api/DependencyScope.java
+++ b/api/maven-api-core/src/main/java/org/apache/maven/api/DependencyScope.java
@@ -33,6 +33,18 @@
* For a given dependency, the scope is directly derived from the
* {@link org.apache.maven.api.model.Dependency#getScope()} and will be used
when using {@link PathScope}
* and the {@link org.apache.maven.api.services.DependencyResolver}.
+ * <p>
+ * Each scope controls which {@link PathScope} classpaths the dependency
appears on
+ * (see {@link PathScope#MAIN_COMPILE}, {@link PathScope#MAIN_RUNTIME},
+ * {@link PathScope#TEST_COMPILE}, {@link PathScope#TEST_RUNTIME}),
+ * and whether the dependency is propagated transitively to downstream projects
+ * (see {@link #isTransitive()}).
+ * <p>
+ * When resolving the transitive graph of a dependency, the effective scope of
its transitive
+ * dependencies may be narrowed. In particular, transitive {@code compile} and
{@code runtime}
+ * dependencies of a {@link #PROVIDED} dependency are pulled in with effective
{@code provided}
+ * scope, while transitive {@code provided} and {@code test} dependencies of a
{@code provided}
+ * dependency are omitted entirely.
*
* @since 4.0.0
* @see org.apache.maven.api.model.Dependency#getScope()
@@ -58,41 +70,68 @@ public enum DependencyScope {
/**
* Compile only.
+ * <p>
+ * A dependency required for compiling the main project code, but
available only on the main
+ * compile classpath. It is not available on the main runtime, test
compile, or test runtime
+ * classpaths.
*/
COMPILE_ONLY("compile-only", false),
/**
- * Compile, runtime and test.
+ * Compile.
+ * <p>
+ * A dependency required for compiling, testing, and running the project.
+ * Dependencies in this scope are available on all classpaths and are
transitive.
*/
COMPILE("compile", true),
/**
- * Runtime and test.
+ * Runtime.
+ * <p>
+ * A dependency not required for compiling the project source code, but
required for executing
+ * the project and running tests. Dependencies in this scope are available
on the main runtime
+ * and test runtime classpaths, but not on the main compile or test
compile classpaths.
+ * Dependencies in this scope are transitive.
*/
RUNTIME("runtime", true),
/**
* Provided.
+ * <p>
+ * A dependency required for compilation and testing that is expected to
be provided at runtime
+ * by the JDK or the runtime environment/container. Dependencies in this
scope are available on
+ * the main compile, test compile, and test runtime classpaths, but not on
the main runtime
+ * classpath. Dependencies in this scope are not transitive to downstream
projects.
*/
PROVIDED("provided", false),
/**
* Test compile only.
+ * <p>
+ * A dependency required only for compiling the test sources, but not
needed for running tests.
*/
TEST_ONLY("test-only", false),
/**
- * Test compile and test runtime.
+ * Test.
+ * <p>
+ * A dependency required for compiling and running tests, but not required
for compiling or
+ * running the main project code. Dependencies in this scope are not
transitive.
*/
TEST("test", false),
/**
* Test runtime.
+ * <p>
+ * A dependency not required for compiling test sources, but required for
executing tests.
*/
TEST_RUNTIME("test-runtime", false),
/**
- * System scope.
+ * System.
+ * <p>
+ * Similar to {@link #PROVIDED}, but the artifact is bound to an explicit
path on the local file system
+ * rather than resolved from a repository.
*/
SYSTEM("system", false);