blob: 96d23bcce65edcdeb24c7f0231a93a1628fb775d [file] [log] [blame]
<?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="https://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: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>
<li>
<a href="vote-txt.html">org.apache.commons:commons-release-plugin:1.6:vote-txt</a>
</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.7</version>
<configuration>
<distSvnStagingUrl>scm:svn:https://dist.apache.org/repos/dist/dev/commons/foo</distSvnStagingUrl>
<isDistModule>true</isDistModule>
</configuration>
<executions>
<execution>
<id>clean-staging</id>
<phase>post-clean</phase>
<goals>
<goal>clean-staging</goal>
</goals>
</execution>
<execution>
<id>detach-distributions</id>
<phase>verify</phase>
<goals>
<goal>detach-distributions</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="https://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] [-Dcommons.release.dryRun=true -Ptest-deploy] -Prelease clean test site deploy
]]></source>
</li>
</ol>
To avoid specifying distribution credentials at the command
line, consider using the <code>distServer</code> plugin configuration parameter (property <code>commons.distServer</code>)
to specify a server definition in Maven <code>settings.xml</code> which defines your (encrypted, right?) authentication info.
</p>
<p>
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>-Dcommons.release.dryRun=true -Ptest-deploy</code>.
</p>
</section>
</body>
</document>