------
 Usage
 ------
 Benson Margulies
 ------
 2012-02-25
 ------

~~ 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


Usage

 The maven-scm-publish-plugin submits modified content to SCM, sites being the most classical case.

 The standard use for sites is:

+-----------+
mvn -Preporting site site:stage
mvn scm-publish:publish-scm
+-----------+

 which will work both for multi-and mono-modules sites.

* Usage With Lifecycle (beta)

 There are two ways you can set this up for site in your POM.

** Use the Custom Lifecycle

  Unfortunately, a Maven plugin can't define a top-level lifecycle
  like 'site'. However, it can come close. The plugin includes the 
  <scmpublish> goal. This goal does nothing except fork a custom
  <scmpublish> lifecycle, consisting of the following phases:

  * <<<scmpublish-prepare>>>

  * <<<scmpublish-pre-site>>>

  * <<<scmpublish-site>>>

  * <<<scmpublish-post-site>>>

  * <<<scmpublish-publish>>>

  []

  (Again unfortunately, Maven does not allow a custom lifecycle to share
  phases with some other lifecycle.)

  With a little configuration in your POM, 

+---------+
  mvn scm-publish:scmpublish
+---------+

  will do all the work.   

+------+
  <build>
    <pluginManagement>
      <plugins>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-scm-publish-plugin</artifactId>
          <version>${project.version}</version>
          <extensions>true</extensions>
          <configuration>
            <!-- svn location for publication -->                  
            <pubScmUrl>scm:svn:https://svn.apache.org/repos/asf/maven/sandbox/bimargulies/site-test-003</pubScmUrl>
          </configuration>
        </plugin>
      </plugins>
    </pluginManagement>
  </build>
+------+

  <Notice>: this is actually not working, the 003-lifecycle IT has been disabled.


** Using the Site Lifecycle

   The alternative is to attach the necessary activities to the site lifecycle and deactivate
   maven-site-plugin's site deploy goal. This requires more XML in the POM, but it may be easier
   to use if you already customize the site lifecycle for other reasons.

+-----+
  <distributionManagement>
    <site>
      <id>site</id>
      <url>scm:svn:https://svn.apache.org/repos/asf/maven/sandbox/bimargulies/site-test</url>
    </site>
  </distributionManagement>
  <build>
    <pluginManagement>
      <plugins>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-site-plugin</artifactId>
          <configuration>
            <skipDeploy>true</skipDeploy>
          </configuration>
        </plugin>
      </plugins>
    </pluginManagement>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-site-plugin</artifactId>
        <executions>
          <execution>
            <id>stage-for-scm-publish</id>
            <phase>post-site</phase>
            <goals>
              <goal>stage</goal>
            </goals>
            <configuration>
              <skipDeploy>false</skipDeploy><!-- MSITE-652: configuration won't be necessary with m-site-p 3.2 -->
            </configuration>
          </execution>
        </executions>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-scm-publish-plugin</artifactId>
        <version>${project.version}</version>
        <executions>
          <execution>
            <id>scm-publish</id>
            <phase>site-deploy</phase>
            <goals>
              <goal>publish-scm</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
+-----+