You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by ch...@apache.org on 2018/01/10 15:08:11 UTC
commons-release-plugin git commit: COMMONSSITE-97: how to do
development on the plugin
Repository: commons-release-plugin
Updated Branches:
refs/heads/master f7041c039 -> 827a19da1
COMMONSSITE-97: how to do development on the plugin
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/827a19da
Tree: http://git-wip-us.apache.org/repos/asf/commons-release-plugin/tree/827a19da
Diff: http://git-wip-us.apache.org/repos/asf/commons-release-plugin/diff/827a19da
Branch: refs/heads/master
Commit: 827a19da14217197f2762e19065193220440793a
Parents: f7041c0
Author: Rob Tompkins <ch...@capitalone.com>
Authored: Wed Jan 10 10:08:05 2018 -0500
Committer: Rob Tompkins <ch...@capitalone.com>
Committed: Wed Jan 10 10:08:05 2018 -0500
----------------------------------------------------------------------
src/site/xdoc/development.xml | 115 ++++++++++++++++++++++---------------
1 file changed, 70 insertions(+), 45 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/commons-release-plugin/blob/827a19da/src/site/xdoc/development.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/development.xml b/src/site/xdoc/development.xml
index afd5186..8daede3 100644
--- a/src/site/xdoc/development.xml
+++ b/src/site/xdoc/development.xml
@@ -39,57 +39,79 @@
<section name="New Mojos">
<p>
- Each Mojo is a java file that extends <code>Abstract</code>
- <ul>
- <li>An ant build file
- <ul><li>[naming convention: <i>basename</i><b>.build.xml</b>]</li></ul>
- </li>
- <li>A <i>mapping document</i> which wires the build file into maven's plugin framework
- <ul><li>[naming convention: <i>basename</i><b>.mojos.xml</b>]</li></ul>
- </li>
- </ul>
+ Each Mojo is a java file that extends <code>AbstractMojo</code> that contains an annotation specifying
+ the goal name for the mojo and the maven lifecycle phase that it executes under by default. For, example
+<source><![CDATA[
+package org.apache.commons.release.plugin.mojos;
+
+@Mojo(name = "detach-distributions", defaultPhase = LifecyclePhase.VERIFY, threadSafe = true)
+public class CommonsDistributionDetachmentMojo extends AbstractMojo {
+ .....
+}]]></source>
+ specifies the goal <code>commons-release:detach-distributions</code> that is to occur during the VERIFY maven
+ lifecycle.
</p>
<p>
- So if you want to add a new <i>foo-bar</i> ant script you would create a <code>foo-bar.build.xml</code>
- ant script file and <code>foo-bar.mojos.xml</code> mapping document.
- </p>
-
- <p>
- Both these files should be located in the
- <a href="http://svn.apache.org/repos/asf/commons/proper/commons-build-plugin/trunk/src/main/scripts/">src/main/scripts</a>
- directory.
- </p>
-
- <p>
- If you want to access variables from the component's <code>pom.xml</code> in the ant script
- then you need to do two things in the <i>mapping document</i>:
- <ul>
- <li>Add the <code><requiresProject>true</requiresProject></code></li>
- <li>Add <code><parameter></code> elements for each of the variables you
- want to use.</li>
- </ul>
- </p>
-
- </section>
-
- <section name="Goal Prefix">
-
- <p>
- This plugin uses <code>commons</code> as the goal prefix. So if you add a new <code>foo-bar</code>
- goal, then it can be executed on the command line using <code>mvn commons:foo-bar</code>. This prefix
- is defined in this plugin's
- <a href="http://svn.apache.org/repos/asf/commons/proper/commons-build-plugin/trunk/pom.xml">pom.xml</a>.
+ The variables in the mojo that are declared as private with the annotations <code>@Parameter</code> get
+ imported to the Mojo by the existent maven variables or the declared <code><configuration></code>. For
+ example, we have a boolean variable named <code>dryRun</code> declared as:
+<source><![CDATA[
+@Parameter
+private Boolean dryRun;
+]]></source>
+ that can be configured by
+<source><![CDATA[
+<plugin>
+ <groupId>org.apache.commons</groupId>
+ <artifactId>commons-release-plugin</artifactId>
+ <version>0.1-SNAPSHOT</version>
+ <configuration>
+ <dryRun>true</dryRun>
+ </configuration>
+</plugin>]]></source>
</p>
</section>
- <section name="Modifying Existing Scripts">
+ <section name="Unit testing">
<p>
- Not alot to say about this except, if you need access to additional variables from the component's
- <code>pom.xml</code> in the ant build script then you will need to define additional <i>parameters</i>
- for these in the associated <i>mapping document</i>.
+ We've declared mock maven poms in the <code>resources</code> directory of the <code>src/test</code> folder,
+ under which we've stored in subdirectories corresponding to the names of the mojos that they are testing. All
+ variables that you wish to be available to your mojo must be specifically declared in the mock pom file. For
+ example, we need to use the already existent <code>MavenProject</code> in the maven runtime by instead, in a
+ test package declaring a class extending <code>MavenProjectStub</code> that returns values we wish to be used
+ in testing. We then add this to our pom in the following declaration of the plugin:
+ <source><![CDATA[
+<plugin>
+ <groupId>org.apache.commons</groupId>
+ <artifactId>commons-release-plugin</artifactId>
+ <configuration>
+ <project implementation="org.apache.commons.release.plugin.stubs.DistributionDetachmentProjectStub" />
+ <workingDirectory>target/commons-release-plugin</workingDirectory>
+ <distSvnStagingUrl>mockDistSvnStagingUrl</distSvnStagingUrl>
+ </configuration>
+</plugin>]]></source>
+ Also note here we are declaring other values that we are using in the testing of the plugin. We then retrieve
+ our instantiated mojo by declaring a <code>MojoRule</code> in our test class,
+<source><![CDATA[
+@Rule
+public MojoRule rule = new MojoRule() {
+ @Override
+ protected void before() throws Throwable {
+ }
+
+ @Override
+ protected void after() {
+ }
+};]]></source>
+ and then retrieve the mojo by newing up a <code>File</code> pointed to the path of the mock pom, and then
+ making the following call:
+<source><![CDATA[
+mojo = (CommonsSiteCompressionMojo) rule.lookupMojo("compress-site", testPom);
+]]></source>
+ where we are trying to get the mojo with the <code>compress-site</code> goal.
</p>
</section>
@@ -97,11 +119,14 @@
<section name="Debugging">
<p>
- The <i>message level</i> for ant is <i>info</i> by default. Running the plugin goal using a message
- level of <i>debug</i> can help in discovering problems - for example:
+ Maven ships with a debugger under the hood. It is suggested that you have a sandbox project in which you can
+ run the goals or the plugin configuration. Once you have that set up you can run something like
<source><![CDATA[
- mvn commons:jira-page -DantMessageLevel=debug
+mvnDebug commons-release:detach-distributions
]]></source>
+ which exposes a remote debugger on port 8000 and halts the maven process until you attach a remote debugger
+ to that port. Once you have a remote debugger attached the maven process continues and stops at any
+ breakpoints that you have set up in your project.
</p>
</section>