------
  Usage
  ------
  Carlos Sanchez <carlos@apache.org>
  Brett Porter <brett@apache.org>
  John Tolentino <jtolentino@apache.org>
  Robert Scholte <rfscholte@apache.org>
  ------
  2011-11-10
  ------

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

Usage

* Prepare your project to use the maven-release-plugin

  To be able to make a solid start with the maven-release-plugin, there are 2 things you should include in our pom:
  
  * the <<<scm>>>-section with a <<<developerConnection>>>
  
  * the maven-release-plugin with a locked version
  
  []
  
  The <<<developerConnection>>> contains the URL of the Source Control Management system pointing to the folder containing this <<<pom.xml>>>
  This URL is prefixed with <<<scm:[scm-provider]>>> so the plugin can pick the right implementation for committing and tagging.
  The {{{http://maven.apache.org/scm/scms-overview.html}Maven SCM}}-page contains an overview all the supported SCMs, per SCM you can see how the URL should look like. 
  
+--------

<project>
  ...
  <scm>
    <developerConnection>scm:svn:https://svn.mycompany.com/repos/myapplication/trunk/mycomponent/</developerConnection>
  </scm>
  
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-release-plugin</artifactId>
        <version>${project.version}</version>
      </plugin>
    </plugins>
    ...
  </build>
  ...
</project>

+-------

=======================================================================

  The following are some common scenarios in preparing a release.

* Use a different username in the SCM server than the one in the operating system

  Most of the SCMs are simply executed as an external command as the current user on your system. If this username is
  not the same as the SCM username, you may need to set the following option:

+------
mvn -Dusername=your_scm_username release:prepare
+------

* Set where to tag the files in Subversion

  This example shows how to set the repository location for all tags to be created in Subversion.
  Note that this is not needed if you use the standard SVN layout, where the root project is in <<<trunk>>>, and
  there is a sibling <<<tags>>> directory.

+-------------------
<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-release-plugin</artifactId>
        <version>${project.version}</version>
        <configuration>
          <tagBase>https://svn.mycompany.com/repos/myapplication/releases</tagBase>
        </configuration>
      </plugin>
    </plugins>
    ...
  </build>
  ...
</project>
+-------------------

* Do a Dry Run

  Since the Release Plugin performs a number of operations that change the project, it may be wise to do a dry run
  before a big release or on a new project. To do this, commit all of your files as if you were about to run a full
  release and run:

+------
mvn release:prepare -DdryRun=true
+------

  This will ask all the same questions, run the same tests, and output a copy of how the POMs will look after
  transformation. You can check the output and review the POMs, then run:

+------
mvn release:clean
+------

  This will remove all of the files created above, and the project will be ready to execute the proper release.

* Run in Batch Mode

  Sometimes it is desirable to do the commit/tag process on a regular interval (e.g. to produce nightly or integration
  builds through a build server). To use the default inputs for the versions and tag information and not prompt for any
  values, use Maven's <<<--batch-mode>>> setting:

+------
mvn --batch-mode release:prepare
+------

* Use a staging repository

  Sometimes it is desirable to deploy a pre-release to be approved before made publicly available. One option is to
  create release candidates versions using the <<<release:perform>>> goal, but the final deployed artifact will NOT
  be the exact one that has been approved as RCx.

  A common solution is to use a staging repository, where a test-version is deployed with it's documentation for
  review. If all is fine, it is then copied to the public repository. Using this strategy, the artifact that has
  been tested IS the one that is deployed.

  The <<<release:stage>>> goal uses this strategy. It replaces the <<<release:perform>>> goal and does the same
  tasks, but requires a <<<stagingRepository>>> parameter. It will automatically re-configure the <<<deploy>>> and
  <<<site-deploy>>> goals to use the staging strategy.

  After the release is complete, the <<<release.properties>>> and other release files will NOT be removed, so that
  you can still execute a <<<release:rollback>>> if some error has been detected and a new candidate must
  be created after some fixes. You just need to use a distinct tag in SCM, or rename the one that has been created
  if the SCM provider supports renaming tags.