src/site/xdoc/index.xml

<?xml version="1.0" encoding="UTF-8"?>
<!--
   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.
-->
<!--
   $HeadURL$
   $Revision$ $Date$
 -->
<document>

    <properties>
        <title>Overview</title>
        <author email="dev@commons.apache.org">Apache Commons Team</author>
    </properties>

    <body>

        <section name="Release Plugin">

            <p>
            This is a <a href="http://maven.apache.org/">Maven 3.x</a> Plugin which is
            used by <a href="http://commons.apache.org/">Apache Commons</a> releases. See
            the <a href="development.html">Development</a> page for information to
            help maintain this plugin.
            </p>

            <p>The main purpose of the plugin is to automate the steps of our, namely
            The Apache Commons Project's, release process. Currently we have the mechanics
            for detaching distribution artifacts (i.e. all <code>tar.gz</code> artifacts and
            signatures as well as all <code>.zip</code> artifacts and signatures), creating
            a <code>site.zip</code> file, and staging all of those artifacts in a subversion
            repository (for the most part a sub directory of
            <a href="https://dist.apache.org/repos/dist/dev/commons/">https://dist.apache.org/repos/dist/dev/commons/</a>.
            It can, however, stage to any subversion repository.
            </p>

        </section>

        <section name="Plugin Goals">
            <p>
            Available Goals (which are meant to be used together; the only reason they are separated is for
            code readability):
            <ul>
                <li>
                    <b>commons-release:detach-distributions</b> - Remove
                    <code>tar.gz</code>, <code>tar.gz.asc</code>, <code>zip</code>, and <code>zip.asc</code>
                    files from being uploaded to nexus and copy them to the <code>target/commons-release-plugin</code>
                    directory.
                </li>
                <li>
                    <b>commons-release:compress-site</b> - Generate <code>site.zip</code> file
                    in the <code>target/commons-release-plugin</code> directory.</li>
                <li>
                    <b>commons-release:stage-distributions</b> - Take all staged files in the
                    <code>target/commons-release-plugin</code> directory, and the <code>RELEASE-NOTES.txt</code> from
                    the root of the project, and commit them to a specified staging subversion repository.
                </li>
            </ul>
            </p>
        </section>

        <section name="Using the plugin">
            <p>
            Configure the plugin as the last plugin in the<code>&lt;build&gt;</code> section of the <code>pom.xml</code>
<source><![CDATA[
<plugin>
  <groupId>org.apache.commons</groupId>
  <artifactId>commons-release-plugin</artifactId>
  <version>1.0</version>
  <configuration>
    <distSvnStagingUrl>scm:svn:https://dist.apache.org/repos/dist/dev/commons/foo</distSvnStagingUrl>
    <dryRun>${dryRun}</dryRun>
  </configuration>
  <executions>
    <execution>
      <id>detach-distributions</id>
      <phase>verify</phase>
      <goals>
        <goal>detach-distributions</goal>
      </goals>
    </execution>
    <execution>
      <id>compress-site</id>
      <phase>site</phase>
      <goals>
        <goal>compress-site</goal>
      </goals>
    </execution>
    <execution>
      <id>stage-distributions</id>
      <phase>deploy</phase>
      <goals>
        <goal>stage-distributions</goal>
      </goals>
    </execution>
  </executions>
</plugin>
]]></source>
            </p>
            <p>
            After the above configuration performing the release would occur by (<i>note.</i> more
            in depth details can be found at
            <a href="http://commons.apache.org/releases/prepare.html">Preparations For A Release</a>):
                <ol>
                    <li>creating our release branch,</li>
                    <li>checking compatibility,</li>
                    <li>checking your dependencies,</li>
                    <li>checking javadocs and code style,</li>
                    <li>checking the apache license,</li>
                    <li>configure the build to generate a complete set of release artifacts,</li>
                    <li>preparing the release notes, updating the download file and other autogenerated files,</li>
                    <li>tagging the release candidate, and</li>
                    <li>
                        running the following command:
<source><![CDATA[
mvn -Duser.name=<yourApacheId> [-Duser.password=<yourApacheIdsPassword] [-DdryRun=true -Ptest-deploy] -Prelease clean test site deploy
]]></source>
                    </li>
                </ol>
            If the component is new, then, before running this maven command, you would want to create
            the requisite subversion directory <code>https://dist.apache.org/repos/dist/dev/commons/foo</code>. Notice,
            that the way to perform a dry run of the release you need to include
            <code>-DdryRun=true -Ptest-deploy</code>.
            </p>
        </section>

    </body>
</document>