 ------
 Maven Wagon SCM
 ------
 Carlos Sanchez
 ------
 2011-09-22
 ------

 ~~ Licensed to the Apache Software Foundation (ASF) under one
 ~~ or more contributor license agreements.  See the NOTICE file
 ~~ distributed with this work for additional information
 ~~ regarding copyright ownership.  The ASF licenses this file
 ~~ to you under the Apache License, Version 2.0 (the
 ~~ "License"); you may not use this file except in compliance
 ~~ with the License.  You may obtain a copy of the License at
 ~~
 ~~   http://www.apache.org/licenses/LICENSE-2.0
 ~~
 ~~ Unless required by applicable law or agreed to in writing,
 ~~ software distributed under the License is distributed on an
 ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 ~~ KIND, either express or implied.  See the License for the
 ~~ specific language governing permissions and limitations
 ~~ under the License.

 ~~ NOTE: For help with the syntax of this file, see:
 ~~ http://maven.apache.org/doxia/references/apt-format.html

Maven Wagon SCM Usage

 You need to add some extensions to your pom:

 * <<<wagon-scm>>>,

 * {{{/scm/maven-scm-managers/maven-scm-manager-plexus/index.html}<<<maven-scm-manager-plexus>>>}}

 * and the {{{/scm/maven-scm-providers/index.html}Maven SCM Provider}} for your SCM system,

 []

 and use URLs in the {{{/scm/scm-url-format.html}SCM format}}.
 
 For non-subversion SCM, you can include the elements <<<scmVersionType>>> and <<<scmVersion>>> in your <<<settings.xml>>> file to
 specify a branch or tag to use. The value of <<<scmVersionType>>> must be one of <<<branch>>> or <<<tag>>>.
 There is no default value for <<<scmVersionType>>> so you <MUST> specify it with <<<scmVersion>>> in order
 to have any effect.


Deploying your Maven site to SCM

 There are some <<shortcomings>> to simply using Wagon SCM provider with site plugin:

 * generated site may have inconsistent newlines (see {{{https://issues.apache.org/jira/browse/MSITE-121}MSITE-121}}),
 preventing SCM check-in,

 * deploying site to SCM will require obsolete pages deletion, which is not done,

 * site plugin way make one commit per file.

 []

 <<Prefer {{{http://maven.apache.org/plugins/maven-scm-publish-plugin/}maven-scm-publish-plugin}} to
 publish your site to SCM>>

 <<Note for Maven 3 users:>> The site plugin behaves differently, require these
 be added as dependencies instead of extensions. See
 {{{/plugins/maven-site-plugin/examples/adding-deploy-protocol.html}
 Adding a Protocol to Deploy the Site}}.

* Deploying your Maven site to Subversion

 Add the following extensions to your pom and use a wagon-scm url in the distributionManagement site url.

------
  <build>
    <extensions>
      <extension>
        <groupId>org.apache.maven.wagon</groupId>
        <artifactId>wagon-scm</artifactId>
        <version>${project.version}</version>
      </extension>
      <extension>
        <groupId>org.apache.maven.scm</groupId>
        <artifactId>maven-scm-manager-plexus</artifactId>
        <version>${mavenScmVersion}</version>
      </extension>
      <extension>
        <groupId>org.apache.maven.scm</groupId>
        <artifactId>maven-scm-provider-svnexe</artifactId>
        <version>${mavenScmVersion}</version>
      </extension>
    </extensions>
  </build>
  <distributionManagement>
    <site>
      <id>my.svn.server</id>
      <url>scm:svn:https://username@svn.apache.org/svn/root/module</url>
    </site>
  </distributionManagement>
------


* Deploying your Maven site to CVS

 Same as before, but changing svnexe to cvsexe and using a CVS svn url.

------
  <build>
    <extensions>
      <extension>
        <groupId>org.apache.maven.wagon</groupId>
        <artifactId>wagon-scm</artifactId>
        <version>${project.version}</version>
      </extension>
      <extension>
        <groupId>org.apache.maven.scm</groupId>
        <artifactId>maven-scm-manager-plexus</artifactId>
        <version>${mavenScmVersion}</version>
      </extension>
      <extension>
        <groupId>org.apache.maven.scm</groupId>
        <artifactId>maven-scm-provider-cvsexe</artifactId>
        <version>${mavenScmVersion}</version>
      </extension>
    </extensions>
  </build>
  <distributionManagement>
    <site>
      <id>my.cvs.server</id>
      <url>scm:cvs:ext:username@cvs.apache.org:/cvs/root:module</url>
    </site>
  </distributionManagement>
------


* Deploying your Maven site to GitHub's gh-pages

 Same as before, but changing svnexe to gitexe and using a Git svn url.

------
  <build>
    <extensions>
      <extension>
        <groupId>org.apache.maven.wagon</groupId>
        <artifactId>wagon-scm</artifactId>
        <version>${project.version}</version>
      </extension>
      <extension>
        <groupId>org.apache.maven.scm</groupId>
        <artifactId>maven-scm-manager-plexus</artifactId>
        <version>${mavenScmVersion}</version>
      </extension>
      <extension>
        <groupId>org.apache.maven.scm</groupId>
        <artifactId>maven-scm-provider-gitexe</artifactId>
        <version>${mavenScmVersion}</version>
      </extension>
    </extensions>
  </build>
  <distributionManagement>
    <site>
      <id>my.git.server</id>
      <url>scm:git:ssh://git@github.com/myuser/myproject.git</url>
    </site>
  </distributionManagement>
  <!-- if the extension mecanism do not work, use plugin dependency instead -->
  <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-site-plugin</artifactId>
        <version>${maven-site-plugin.version}</version>
        <dependencies>
            <dependency>
                <groupId>org.apache.maven.doxia</groupId>
                <artifactId>doxia-module-markdown</artifactId>
                <version>${mavenScmVersion}</version>
               </dependency>
            <dependency>
                <groupId>org.apache.maven.scm</groupId>
                <artifactId>maven-scm-provider-gitexe</artifactId>
                <version>${mavenScmVersion}</version>
            </dependency>
            <dependency>
                <groupId>org.apache.maven.wagon</groupId>
                <artifactId>wagon-scm</artifactId>
                <version>${mavenScmVersion}</version>
            </dependency>
            <dependency>
                <groupId>org.apache.maven.scm</groupId>
                <artifactId>maven-scm-manager-plexus</artifactId>
                <version>${mavenScmVersion}</version>
            </dependency>
        </dependencies>
  </plugin>
------

 And in your settings.xml file:

------
  <server>
    <id>my.git.server</id>
    <username>git</username>
    <configuration>
        <scmVersionType>branch</scmVersionType>
        <scmVersion>gh-pages</scmVersion>
    </configuration>
  </server>
------


Using a SCM-based remote repository in Maven 2


* Using a Subversion-based remote repository in Maven 2

 Not tested yet


* Using a CVS-based remote repository in Maven 2

 Not tested yet
