This is an automated email from the ASF dual-hosted git repository.
slachiewicz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-scm.git
The following commit(s) were added to refs/heads/master by this push:
new 1dcbfe189 [SCM-1015] Document the roles of ScmManager, ScmProvider and
ScmRepository
1dcbfe189 is described below
commit 1dcbfe1893fd76e0d5c3f23321cffcd0f797eeb6
Author: Sylwester Lachiewicz <[email protected]>
AuthorDate: Tue Nov 17 02:11:32 2026 +0100
[SCM-1015] Document the roles of ScmManager, ScmProvider and ScmRepository
Fixes #1239
---
.../src/main/java/org/apache/maven/scm/manager/ScmManager.java | 8 ++++++++
.../src/main/java/org/apache/maven/scm/provider/ScmProvider.java | 8 ++++++++
.../main/java/org/apache/maven/scm/repository/ScmRepository.java | 6 +++++-
3 files changed, 21 insertions(+), 1 deletion(-)
diff --git
a/maven-scm-api/src/main/java/org/apache/maven/scm/manager/ScmManager.java
b/maven-scm-api/src/main/java/org/apache/maven/scm/manager/ScmManager.java
index 3d576c738..c10e1fd00 100644
--- a/maven-scm-api/src/main/java/org/apache/maven/scm/manager/ScmManager.java
+++ b/maven-scm-api/src/main/java/org/apache/maven/scm/manager/ScmManager.java
@@ -52,6 +52,14 @@
import org.apache.maven.scm.repository.UnknownRepositoryStructure;
/**
+ * Entry point for clients: turns SCM URLs into {@link ScmRepository}
instances and looks up the
+ * {@link ScmProvider} responsible for them.
+ * <p>
+ * Most commands offered here are shortcuts which delegate to the same named
method of the provider
+ * of the given repository. The provider is exposed as well (see {@link
#getProviderByRepository(ScmRepository)}),
+ * and some functionality is only available through the provider. The manager
is therefore the higher level
+ * API, while {@link ScmProvider} is both the lower level API and the SPI
implemented by the SCM specific modules.
+ *
* @author <a href="mailto:[email protected]">Trygve Laugstøl</a>
* @author <a href="mailto:[email protected]">Brett Porter</a>
* @author <a href="mailto:[email protected]">Emmanuel Venisse</a>
diff --git
a/maven-scm-api/src/main/java/org/apache/maven/scm/provider/ScmProvider.java
b/maven-scm-api/src/main/java/org/apache/maven/scm/provider/ScmProvider.java
index 8b9adace0..d7ad96f7c 100644
--- a/maven-scm-api/src/main/java/org/apache/maven/scm/provider/ScmProvider.java
+++ b/maven-scm-api/src/main/java/org/apache/maven/scm/provider/ScmProvider.java
@@ -55,6 +55,14 @@
import org.apache.maven.scm.repository.UnknownRepositoryStructure;
/**
+ * The implementation of one SCM type (for example {@code svn} or {@code
git}), registered with the
+ * {@link org.apache.maven.scm.manager.ScmManager}.
+ * <p>
+ * It is the SPI which each SCM specific module implements, and at the same
time the lower level API
+ * for running commands: the {@link org.apache.maven.scm.manager.ScmManager}
offers shortcuts for most, but
+ * not all, of the commands declared here. A provider works on the {@link
ScmProviderRepository} of the
+ * given {@link ScmRepository}.
+ *
* @author <a href="mailto:[email protected]">Emmanuel Venisse</a>
*/
public interface ScmProvider {
diff --git
a/maven-scm-api/src/main/java/org/apache/maven/scm/repository/ScmRepository.java
b/maven-scm-api/src/main/java/org/apache/maven/scm/repository/ScmRepository.java
index 77578292f..a5bdfa3fc 100644
---
a/maven-scm-api/src/main/java/org/apache/maven/scm/repository/ScmRepository.java
+++
b/maven-scm-api/src/main/java/org/apache/maven/scm/repository/ScmRepository.java
@@ -21,8 +21,12 @@
import org.apache.maven.scm.provider.ScmProviderRepository;
/**
+ * A repository as seen by clients of the {@link
org.apache.maven.scm.manager.ScmManager}: it couples the type of the
+ * SCM (the provider name) with the {@link ScmProviderRepository} holding the
provider specific settings
+ * parsed from the SCM URL (location, credentials and the like). Instances are
created by
+ * {@link org.apache.maven.scm.manager.ScmManager#makeScmRepository(String)}.
+ *
* @author <a href="mailto:[email protected]">Emmanuel Venisse</a>
- * TODO clarify need - should be able to merge with ScmProviderRepository?
*/
public class ScmRepository {
private String provider;