Author: evenisse
Date: Tue Mar 27 08:40:00 2007
New Revision: 522960
URL: http://svn.apache.org/viewvc?view=rev&rev=522960
Log:
[SCM-6] Add provider development documentation
Modified:
maven/scm/trunk/maven-scm-site/src/site/apt/guide/new_provider.apt
Modified: maven/scm/trunk/maven-scm-site/src/site/apt/guide/new_provider.apt
URL:
http://svn.apache.org/viewvc/maven/scm/trunk/maven-scm-site/src/site/apt/guide/new_provider.apt?view=diff&rev=522960&r1=522959&r2=522960
==============================================================================
--- maven/scm/trunk/maven-scm-site/src/site/apt/guide/new_provider.apt
(original)
+++ maven/scm/trunk/maven-scm-site/src/site/apt/guide/new_provider.apt Tue Mar
27 08:40:00 2007
@@ -3,12 +3,12 @@
------
Maven Team
------
- 12 March 2007
+ 27 March 2007
------
-<<This document is a Draft.>>
+How to write a new Maven-SCM provider?
-Steps to write a new Maven-SCM provider?
+* What are the steps to write a new Maven-SCM provider?
* define allowed scm urls for this provider
@@ -23,8 +23,174 @@
* for each commands, implements TCK tests.
+ * test the release plugin with the new provider. For that, you must to add
the dependency to the release plugin and run it
+
+ * Add the dependency to Continuum libs and test the provider with a sample
project
+
* update the site
- * test the release plugin with the new provider. For that, you need to add
the dependency to the release plugin and run it
+ In next section, we'll see all steps in details to write a new Maven-SCM
provider.
- * Add the dependency to Continuum libs and test the provider with a sample
project
+* Create a new Maven project for the provider
+
+ Your project need to use some jars from the Maven-SCM framework. Add them
to your POM.
+
++------------------------------------------+
+<project xmlns="http://maven.apache.org/POM/4.0.0";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
http://maven.apache.org/maven-v4_0_0.xsd";>
+ <parent>
+ <artifactId>maven-scm-providers</artifactId>
+ <groupId>org.apache.maven.scm</groupId>
+ <version>LATEST VERSION OF MAVEN-SCM PROVIDERS MASTER POM</version>
+ </parent>
+ <modelVersion>4.0.0</modelVersion>
+ <artifactId>maven-scm-provider-YOUR_PROVIDER_NAME</artifactId>
+ <name>My Maven-SCM Provider</name>
+ <version>1.0-SNAPSHOT</version>
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.codehaus.plexus</groupId>
+ <artifactId>plexus-maven-plugin</artifactId>
+ <executions>
+ <execution>
+ <goals>
+ <goal>descriptor</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+</project>
++------------------------------------------+
+
+ The plexus maven plugin will generate the plexus meta-data file used by
the Maven-SCM manager.
+
+* Create a SCM Provider Repository class
+
+ This class will contain all SCM informations about your SCM connection
(user, password, host, port, path...)
+
++------------------------------------------+
+package org.apache.maven.scm.provider.myprovider.repository;
+
+import org.apache.maven.scm.provider.ScmProviderRepository;
+
+public class MyScmProviderRepository
+ extends ScmProviderRepository
+{
+}
++------------------------------------------+
+
+ Before to add more informations in this class, you can look at
ScmProviderRepository sub-classes if they are already implemented.
+
+* Create the Provider class
+
+ This class is the central point of the provider. The Maven-SCM framework
will know only this class in the provider, so this class must validate the scm
url,
+ populate the ScmProviderRepository and provide all commands supported by
your provider. We start with a basic class, then we'll add command in it when
they
+ will be implemented.
+
+ Before to start to write your SCM provider, you must define SCM URLs you
want to support.
+
++------------------------------------------+
+package org.apache.maven.scm.provider.myprovider;
+
+import
org.apache.maven.scm.provider.myprovider.repository.MyScmProviderRepository;
+
+import org.apache.maven.scm.provider.AbstractScmProvider;
+import org.apache.maven.scm.provider.ScmProviderRepository;
+import org.apache.maven.scm.repository.ScmRepositoryException;
+
+/**
+ * @plexus.component role="org.apache.maven.scm.provider.ScmProvider"
role-hint="provider_name"
+ */
+public class MyScmProvider
+ extends AbstractScmProvider
+{
+ public String getScmType()
+ {
+ return "provider_name";
+ }
+
+ /**
+ * This method parse the scm URL and return a SCM provider repository.
+ * At this point, the scmSpecificUrl is the part after scm:provider_name:
in your SCM URL.
+ */
+ public ScmProviderRepository makeProviderScmRepository( String
scmSpecificUrl, char delimiter )
+ throws ScmRepositoryException
+ {
+ MyScmProviderRepository providerRepository = new
MyScmProviderRepository();
+ //Parse scmSpecificUrl and populate there your provider repository
+
+ return providerRepository;
+ }
+}
++------------------------------------------+
+
+ The <plexus.component> javadoc tag will be used by the the plexus maven
plugin, declared in the POM, to generate plexus meta-data.
+ Generally, we use for the <provider_name>, the string just after <scm:> in
the scm URL.
+
+* Commands implementation
+
+ When you write a new SCM command, you must extends base classes for the
Maven-SCM framework. We have one base command for each command supported by
Maven-SCM
+ and each command have an execute method that return a SCM result.
+
++------------------------------------------+
+package org.apache.maven.scm.provider.myprovider.command.checkout;
+
+import org.apache.maven.scm.command.checkout.AbstractCheckOutCommand;
+
+public class MyCheckoutCommand
+ extends AbstractCheckOutCommand
+{
+ protected abstract CheckOutScmResult executeCheckOutCommand(
ScmProviderRepository repository, ScmFileSet fileSet, String tag )
+ throws ScmException
+ {
+ CheckOutScmResult result = new CheckOutScmResult();
+
+ //Add the code there to run the command
+ //If you need to run a native commandline like cvs/svn/cleartool...,
look at other providers how to launch it and parse the output
+
+ return result;
+ }
+}
++------------------------------------------+
+
+* Allow the command in the SCM provider
+
+ Now your command is implemented, you need to add it in your SCM provider
(MyScmProvider). Open the provider class and override the method that related
to your command.
+
++------------------------------------------+
+public class MyScmProvider
+ extends AbstractScmProvider
+{
+ ...
+
+ protected CheckOutScmResult checkout( ScmRepository repository, ScmFileSet
fileSet, CommandParameters params )
+ throws ScmException
+ {
+ MyCheckoutCommand command = new MyCheckoutCommand();
+ command.setLogger( getLogger() );
+ return (CheckOutScmResult) command.execute(
repository.getProviderRepository(), fileSet, params );
+ }
+}
++------------------------------------------+
+
+* Provider Tests
+
+** Automated tests
+
+ To be sure your provider works as expected, you must implement some tests.
You can implement two levels for tests:
+
+ * Simple JUnit test that use directly your command and test the comman
line you launch in your SCM command is correct
+
+ * Implementation of the TCK. The TCK provide a set of tests that validate
your implementation is compatible with the Maven-SCM framework. The TCK
required access to the SCM tool.
+
+** Other tests
+
+ You can do manual test in real world with the maven Maven-SCM plugin, the
maven release plugin, the maven changelog plugin and Continuum.
+
+ It's important to test your SCM providers with these tools, because they
are used by users that will be use your provider.
+
+* Document your provider
+
+ Now your provider works fine, you must document it (scm URLs supported,
command supported...). You can use the same template used by other providers.
