Repository: commons-release-plugin Updated Branches: refs/heads/master ea2fb4e75 -> 3250bf66b
COMMONSSITE-97: Providing better documentation and testing javadocs Project: http://git-wip-us.apache.org/repos/asf/commons-release-plugin/repo Commit: http://git-wip-us.apache.org/repos/asf/commons-release-plugin/commit/ec846af9 Tree: http://git-wip-us.apache.org/repos/asf/commons-release-plugin/tree/ec846af9 Diff: http://git-wip-us.apache.org/repos/asf/commons-release-plugin/diff/ec846af9 Branch: refs/heads/master Commit: ec846af9085cad8f42304b185f5bb5666ce33af5 Parents: 34e727b Author: Rob Tompkins <chtom...@gmail.com> Authored: Tue Jan 9 08:30:55 2018 -0500 Committer: Rob Tompkins <chtom...@gmail.com> Committed: Tue Jan 9 08:30:55 2018 -0500 ---------------------------------------------------------------------- src/site/site.xml | 8 +- src/site/xdoc/index.xml | 94 ++++++++++++++++---- .../release/plugin/mojos/package-info.java | 7 ++ .../commons/release/plugin/package-info.java | 7 ++ .../DistributionDetachmentProjectStub.java | 6 +- .../release/plugin/stubs/package-info.java | 10 +++ 6 files changed, 111 insertions(+), 21 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/commons-release-plugin/blob/ec846af9/src/site/site.xml ---------------------------------------------------------------------- diff --git a/src/site/site.xml b/src/site/site.xml index 1c5d926..27a1a2d 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -19,16 +19,14 @@ $HeadURL$ $Revision$ $Date$ --> -<project name="Commons Build Plugin"> +<project name="Commons Release Plugin"> <body> - <menu name="Build Plugin"> - <item name="Overview" href="/index.html"/> + <menu name="Release Plugin"> + <item name="Overview" href="/index.html" /> <item name="Help" href="/development.html"> <item name="Issue Tracking" href="/issue-tracking.html"/> <item name="Development" href="/development.html"/> - <item name="Maven Plugins" href="http://maven.apache.org/guides/plugin/guide-ant-plugin-development.html"/> - <item name="Ant" href="http://ant.apache.org/manual/index.html"/> </item> </menu> </body> http://git-wip-us.apache.org/repos/asf/commons-release-plugin/blob/ec846af9/src/site/xdoc/index.xml ---------------------------------------------------------------------- diff --git a/src/site/xdoc/index.xml b/src/site/xdoc/index.xml index eb02ced..cb38844 100644 --- a/src/site/xdoc/index.xml +++ b/src/site/xdoc/index.xml @@ -23,7 +23,7 @@ <properties> <title>Overview</title> - <author email="d...@commons.apache.org">Apache Commons Documentation Team</author> + <author email="d...@commons.apache.org">Apache Commons Team</author> </properties> <body> @@ -31,42 +31,106 @@ <section name="Release Plugin"> <p> - This is a <a href="http://maven.apache.org/";>Maven 2.x/3.x</a>Plugin which is + 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: + Available Goals (which are meant to be used together; the only reason they are separated is for + code readability): <ul> - <li><a href="download-page.html">commons:download-page</a> - Generate a Download page for the component's latest release</li> - <li><a href="mail-page.html">commons:mail-page</a> - Generate a custom <i>Mailing List</i> page for a component</li> - <li><a href="jira-page.html">commons:jira-page</a> - Generate a custom <i>JIRA Issue Tracking</i> page for a component</li> - <li><a href="sandbox-jira-page.html">commons:sandbox-jira-page</a> - Generate a custom <i>JIRA Issue Tracking page</i> for a Sandbox component</li> - <li><a href="copy-javadoc-files-build.html">commons:copy-javadoc-files</a> - Copy NOTICE and LICENSE files to -javadoc jar</li> - <li><a href="readme-md.html">commons:readme-md</a> - Generate a README.md file containing information for contributors from GitHub</li> - <li><a href="contributing-md.html">commons:contributing-md</a> - Generate a CONTRIBUTING.md file containing information on how to contribute for contributors from GitHub</li> + <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="Trying out the plugin"> + <section name="Using the plugin"> <p> - Configure the plugin in the <code><build></code> section of the <code>pom.xml</code> + Configure the plugin as the last plugin in the<code><build></code> section of the <code>pom.xml</code> <source><![CDATA[ <plugin> <groupId>org.apache.commons</groupId> - <artifactId>commons-build-plugin</artifactId> - <version>1.6</version> + <artifactId>commons-release-plugin</artifactId> + <version>0.1-SNAPSHOT</version> + <configuration> + <distSvnStagingUrl>scm:svn:https://dist.apache.org/repos/dist/dev/commons/foo</distSvnStagingUrl> + </configuration> + <executions> + <execution> + <id>detatch-distributions</id> + <phase>verify</phase> + <goals> + <goal>detatch-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> - Configure any properties required by the goal and try executing. + 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> -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>. </p> </section> http://git-wip-us.apache.org/repos/asf/commons-release-plugin/blob/ec846af9/src/test/java/org/apache/commons/release/plugin/mojos/package-info.java ---------------------------------------------------------------------- diff --git a/src/test/java/org/apache/commons/release/plugin/mojos/package-info.java b/src/test/java/org/apache/commons/release/plugin/mojos/package-info.java index 32828f0..c9ab4b7 100644 --- a/src/test/java/org/apache/commons/release/plugin/mojos/package-info.java +++ b/src/test/java/org/apache/commons/release/plugin/mojos/package-info.java @@ -14,4 +14,11 @@ * See the License for the specific language governing permissions and * limitations under the License. */ +/** + * This package contains the unit tests for the package + * {@link org.apache.commons.release.plugin.mojos}. + * + * @author chtompki + * @since 1.0 + */ package org.apache.commons.release.plugin.mojos; \ No newline at end of file http://git-wip-us.apache.org/repos/asf/commons-release-plugin/blob/ec846af9/src/test/java/org/apache/commons/release/plugin/package-info.java ---------------------------------------------------------------------- diff --git a/src/test/java/org/apache/commons/release/plugin/package-info.java b/src/test/java/org/apache/commons/release/plugin/package-info.java index 4852740..8c9e5ff 100644 --- a/src/test/java/org/apache/commons/release/plugin/package-info.java +++ b/src/test/java/org/apache/commons/release/plugin/package-info.java @@ -14,4 +14,11 @@ * See the License for the specific language governing permissions and * limitations under the License. */ +/** + * This is the base package containing the unit tests + * <code>commons-release-plugin</code>. + * + * @author chtompki + * @since 1.0 + */ package org.apache.commons.release.plugin; \ No newline at end of file http://git-wip-us.apache.org/repos/asf/commons-release-plugin/blob/ec846af9/src/test/java/org/apache/commons/release/plugin/stubs/DistributionDetachmentProjectStub.java ---------------------------------------------------------------------- diff --git a/src/test/java/org/apache/commons/release/plugin/stubs/DistributionDetachmentProjectStub.java b/src/test/java/org/apache/commons/release/plugin/stubs/DistributionDetachmentProjectStub.java index da41efd..7e90b4e 100644 --- a/src/test/java/org/apache/commons/release/plugin/stubs/DistributionDetachmentProjectStub.java +++ b/src/test/java/org/apache/commons/release/plugin/stubs/DistributionDetachmentProjectStub.java @@ -16,6 +16,7 @@ */ package org.apache.commons.release.plugin.stubs; +import org.apache.commons.release.plugin.mojos.CommonsDistributionDetachmentMojoTest; import org.apache.maven.artifact.Artifact; import org.apache.maven.plugin.testing.stubs.ArtifactStub; import org.apache.maven.plugin.testing.stubs.MavenProjectStub; @@ -26,9 +27,12 @@ import java.util.ArrayList; import java.util.List; /** - * Stub for {@link MavenProject} for the {@link CommonsDistributionDetachmentMojoTest}. + * Stub for {@link MavenProject} for the {@link CommonsDistributionDetachmentMojoTest}. See the testing pom, + * <code>src/test/resources/detach-distributions/detach-distributions.xml</code> for the declared usage of + * this class. * * @author chtompki + * @since 1.0 */ public class DistributionDetachmentProjectStub extends MavenProjectStub { http://git-wip-us.apache.org/repos/asf/commons-release-plugin/blob/ec846af9/src/test/java/org/apache/commons/release/plugin/stubs/package-info.java ---------------------------------------------------------------------- diff --git a/src/test/java/org/apache/commons/release/plugin/stubs/package-info.java b/src/test/java/org/apache/commons/release/plugin/stubs/package-info.java index 95d9137..b0a334f 100644 --- a/src/test/java/org/apache/commons/release/plugin/stubs/package-info.java +++ b/src/test/java/org/apache/commons/release/plugin/stubs/package-info.java @@ -14,4 +14,14 @@ * See the License for the specific language governing permissions and * limitations under the License. */ +/** + * This package is meant to contain stubbed objects for the maven testing + * paradigm. These stubs can in turn be used in the poms in the <code>src/test/resources</code> + * directory of the project in the implementation block of the declaration of the configuration + * property. The maven unit testing framework then wires this stubbed object into the appropriate mojo + * for testing purposes. + * + * @author chtompki + * @since 1.0 + */ package org.apache.commons.release.plugin.stubs; \ No newline at end of file
