<?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>Development</title>
    <author email="dev@commons.apache.org">Apache Commons Documentation Team</author>
  </properties>

  <body>

    <section name="Help with Maven Mojos">

      <p>
        The best sources of information are
        <a href="http://maven.apache.org/guides/plugin/guide-java-plugin-development.html">Developing Java Plugins for Maven 3.x</a>
        and <a href="http://www.sonatype.com/book/chapter-11.html">Maven: The Definitive Guide: Chapter 11 Writing Plugins</a>.
      </p>

    </section>

    <section name="New Mojos">

      <p>
        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>
        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>&lt;configuration&gt;</code>. For
        example, we have a boolean variable named <code>dryRun</code> declared as:
<source><![CDATA[
@Parameter(property = "commons.release.dryRun", defaultValue = "false")
private Boolean dryRun;
]]></source>
        that can be configured by
<source><![CDATA[
<plugin>
  <groupId>org.apache.commons</groupId>
  <artifactId>commons-release-plugin</artifactId>
  <version>1.7</version>
  <configuration>
    <dryRun>true</dryRun>
  </configuration>
</plugin>]]></source>

        And, because we've set the <code>property here</code> (as in the 1.1 release), you can, on the command line,
        use the following <code>-Dcommons.release.dryRun=true</code>.
      </p>

    </section>

    <section name="Unit testing">

      <p>
        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>

    <section name="Debugging">

      <p>
        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[
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>

  </body>
</document>