commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From chtom...@apache.org
Subject [1/3] commons-release-plugin git commit: COMMONSSITE-97: Providing better documentation and testing javadocs
Date Tue, 09 Jan 2018 13:32:31 GMT
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 <chtompki@gmail.com>
Authored: Tue Jan 9 08:30:55 2018 -0500
Committer: Rob Tompkins <chtompki@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="dev@commons.apache.org">Apache Commons Documentation Team</author>
+        <author email="dev@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>&lt;build&gt;</code> section
of the <code>pom.xml</code>
+            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-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


Mime
View raw message