You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by bu...@apache.org on 2012/12/10 09:17:44 UTC
svn commit: r841370 [5/47] - in /websites/staging/maven/trunk/content: ./
ant/ background/ css/ developers/ developers/conventions/
developers/release/ developers/website/ docs/ docs/2.0.1/ docs/2.0.10/
docs/2.0.11/ docs/2.0.2/ docs/2.0.3/ docs/2.0.4/ ...
Added: websites/staging/maven/trunk/content/developers/mojo-api-specification.html
==============================================================================
--- websites/staging/maven/trunk/content/developers/mojo-api-specification.html (added)
+++ websites/staging/maven/trunk/content/developers/mojo-api-specification.html Mon Dec 10 08:17:24 2012
@@ -0,0 +1,1111 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<!--
+ | Generated by Apache Maven Doxia at Dec 10, 2012
+ | Rendered using Apache Maven Stylus Skin 1.5
+-->
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <title>Maven -
+ Mojo API Specification</title>
+ <style type="text/css" media="all">
+ @import url("../css/maven-base.css");
+ @import url("../css/maven-theme.css");
+ @import url("../css/site.css");
+ </style>
+ <link rel="stylesheet" href="../css/print.css" type="text/css" media="print" />
+ <meta name="author" content="John Casey" />
+ <meta name="Date-Revision-yyyymmdd" content="20121210" />
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+
+<script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script>
+
+<script type="text/javascript">_uacct = "UA-140879-1";
+ urchinTracker();</script>
+ </head>
+ <body class="composite">
+ <div id="banner">
+ <a href=".././" id="bannerLeft">
+ <img src="../images/apache-maven-project-2.png" alt="" />
+ </a>
+ <span id="bannerRight">
+ <img src="../images/maven-logo-2.gif" alt="" />
+ </span>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="breadcrumbs">
+
+ <div class="xleft">
+ <a href="http://www.apache.org/" class="externalLink">Apache</a>
+ >
+ <a href="../index.html">Maven</a>
+ >
+
+ Mojo API Specification
+ </div>
+ <div class="xright">
+ Last Published: 2012-12-10
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="leftColumn">
+ <div id="navcolumn">
+
+ <h5>Main</h5>
+ <ul>
+ <li class="none">
+ <a href="../index.html">Welcome</a>
+ </li>
+ </ul>
+ <h5>Get Maven</h5>
+ <ul>
+ <li class="none">
+ <a href="../download.html">Download</a>
+ </li>
+ <li class="none">
+ <a href="../docs/3.0.4/release-notes.html">Release Notes (3.0.4)</a>
+ </li>
+ <li class="none">
+ <a href="../docs/2.2.1/release-notes.html">Release Notes (2.2.1)</a>
+ </li>
+ <li class="none">
+ <a href="../docs/2.0.11/release-notes.html">Release Notes (2.0.11)</a>
+ </li>
+ <li class="none">
+ <a href="../license.html">License</a>
+ </li>
+ </ul>
+ <h5>IDE Integration</h5>
+ <ul>
+ <li class="none">
+ <a href="../eclipse-plugin.html">Eclipse</a>
+ </li>
+ <li class="none">
+ <a href="../netbeans-module.html">NetBeans</a>
+ </li>
+ </ul>
+ <h5>About Maven</h5>
+ <ul>
+ <li class="none">
+ <a href="../what-is-maven.html">What is Maven?</a>
+ </li>
+ <li class="none">
+ <a href="../maven-features.html">Features</a>
+ </li>
+ <li class="none">
+ <a href="../general.html">FAQ (official)</a>
+ </li>
+ <li class="none">
+ <a href="http://docs.codehaus.org/display/MAVENUSER/FAQs-1" class="externalLink">FAQ (unofficial)</a>
+ </li>
+ </ul>
+ <h5>Documentation</h5>
+ <ul>
+ <li class="none">
+ <a href="../plugins/index.html">Maven Plugins</a>
+ </li>
+ <li class="none">
+ <a href="../guides/index.html">Index (category)</a>
+ </li>
+ <li class="none">
+ <a href="../run-maven/index.html">Running Maven</a>
+ </li>
+ <li class="collapsed">
+ <a href="../users/index.html">User Centre</a>
+ </li>
+ <li class="expanded">
+ <a href="../plugin-developers/index.html">Plugin Developer Centre</a>
+ <ul>
+ <li class="none">
+ <a href="../guides/plugin/guide-java-plugin-development.html">Your First Mojo</a>
+ </li>
+ <li class="none">
+ <strong>Mojo API</strong>
+ </li>
+ <li class="none">
+ <a href="../ref/current/index.html">Maven API</a>
+ </li>
+ </ul>
+ </li>
+ <li class="none">
+ <a href="../repository/index.html">Maven Repository Centre</a>
+ </li>
+ <li class="none">
+ <a href="../developers/index.html">Maven Developer Centre</a>
+ </li>
+ <li class="none">
+ <a href="../articles.html">Books and Resources</a>
+ </li>
+ <li class="none">
+ <a href="http://docs.codehaus.org/display/MAVENUSER/Home" class="externalLink">Wiki</a>
+ </li>
+ </ul>
+ <h5>Community</h5>
+ <ul>
+ <li class="none">
+ <a href="../community.html">Community Overview</a>
+ </li>
+ <li class="none">
+ <a href="../guides/development/guide-helping.html">How to Contribute</a>
+ </li>
+ <li class="none">
+ <a href="../guides/mini/guide-maven-evangelism.html">Maven Repository</a>
+ </li>
+ <li class="none">
+ <a href="../users/getting-help.html">Getting Help</a>
+ </li>
+ <li class="none">
+ <a href="../issue-tracking.html">Issue Tracking</a>
+ </li>
+ <li class="none">
+ <a href="../source-repository.html">Source Repository</a>
+ </li>
+ <li class="none">
+ <a href="../team-list.html">The Maven Team</a>
+ </li>
+ </ul>
+ <h5>Project Documentation</h5>
+ <ul>
+ <li class="collapsed">
+ <a href="../project-info.html">Project Information</a>
+ </li>
+ </ul>
+ <h5>Maven Projects</h5>
+ <ul>
+ <li class="none">
+ <a href="../ant-tasks/index.html">Ant Tasks</a>
+ </li>
+ <li class="none">
+ <a href="../archetype/index.html">Archetype</a>
+ </li>
+ <li class="none">
+ <a href="../doxia/index.html">Doxia</a>
+ </li>
+ <li class="none">
+ <a href="../jxr/index.html">JXR</a>
+ </li>
+ <li class="none">
+ <a href="../maven-1.x/index.html">Maven 1.x</a>
+ </li>
+ <li class="none">
+ <a href="../index.html">Maven 2 & 3</a>
+ </li>
+ <li class="none">
+ <a href="../pom/index.html">Parent POMs</a>
+ </li>
+ <li class="none">
+ <a href="../plugins/index.html">Plugins</a>
+ </li>
+ <li class="none">
+ <a href="../plugin-tools/index.html">Plugin Tools</a>
+ </li>
+ <li class="none">
+ <a href="../scm/index.html">SCM</a>
+ </li>
+ <li class="none">
+ <a href="../shared/index.html">Shared Components</a>
+ </li>
+ <li class="none">
+ <a href="../skins/index.html">Skins</a>
+ </li>
+ <li class="none">
+ <a href="../surefire/index.html">Surefire</a>
+ </li>
+ <li class="none">
+ <a href="../wagon/index.html">Wagon</a>
+ </li>
+ </ul>
+ <h5>ASF</h5>
+ <ul>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/how-it-works.html" class="externalLink">How Apache Works</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/" class="externalLink">Foundation</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/sponsorship.html" class="externalLink">Sponsoring Apache</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/thanks.html" class="externalLink">Thanks</a>
+ </li>
+ </ul>
+ <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
+ <img alt="Built by Maven" src="../images/logos/maven-feather.png"/>
+ </a>
+
+ </div>
+ </div>
+ <div id="bodyColumn">
+ <div id="contentBox">
+ <!-- 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. -->
+
+ <div class="section"><h2>Introduction<a name="Introduction"></a></h2>
+ <p>Starting with Maven, plugins can be written in Java or any of a
+ number of scripting languages. Plugins consists of one or more Mojos,
+ each one being the implementation for one of the plugin's goals.
+ Maven tries to stay out of
+ the way of the programmer with its new Mojo API. This opens up the
+ opportunity for many Mojos to be reused outside of Maven, or bridged
+ into Maven from external systems like Ant.</p>
+ <p>NOTE: For now, we will limit the discussion to Java-based Mojos, since
+ each scripting language will present these same basic requirements with
+ various forms of implementation.</p>
+ <p>Although the requirements on Mojos are minimal by design, there are
+ still a very few requirements that Mojo developers must keep in mind. <!-- First, a Mojo must have a method named <code>execute</code> which
+ declares no parameters, and has a void return type. If this method
+ throws an exception, that exception must either be a derivative of
+ <code>java.lang.RuntimeException</code>, or a derivative of
+ <code>org.apache.maven.plugin.MojoExecutionException</code>. It goes
+ without saying that in the latter case, the execute method must declare
+ that it throws this exception. Additionally, Mojos must declare a field
+ for each parameter they specify, and these parameter fields will be
+ populated before execute() is called (Maven does support other
+ mechanisms for parameter injection, but they are not considered part of
+ the preferred practice, and are therefore a topic for an advanced Mojo
+ developer's guide). Finally, all Mojos must be accompanied by metadata
+ describing parameters, lifecycle bindings, etc. This descriptor will be
+ covered in more detail below.</p>
+ <p>While this will satisfy the requirements for execution as a Mojo
+ inside Maven, it is recommended that Mojos implement --> Basically, these Mojo requirements are embodied by the
+ <tt>org.apache.maven.plugin.Mojo</tt>
+ interface, which the Mojo
+ must implement (or else extend its abstract base class counterpart
+ <tt>org.apache.maven.plugin.AbstractMojo</tt>
+ ). This interface
+ guarantees the correct execution contract for the Mojo: no parameters,
+ void return type, and a throws clause that allows only
+ <tt>org.apache.maven.plugin.MojoExecutionException</tt>
+ and its
+ derivatives. It also guarantees that the Mojo will have access to the
+ standard Maven user-feedback mechanism,
+ <tt>org.apache.maven.plugin.logging.Log</tt>
+ , so the Mojo can
+ communicate important events to the console or other log sink.<!-- Using the
+ Plugin/Mojo API will give that Mojo access to the Maven-integrated Log,
+ along with tighter integration into the Maven build. -->
+ </p>
+ <p>As mentioned before, each Plugin - or packaged set of Mojos - must
+ provide a descriptor called
+ <tt>plugin.xml</tt>
+ under the path
+ <tt>META-INF/maven</tt>
+ inside the Plugin jar file. Fortunately,
+ Maven also provides a set of Javadoc annotations and tools to generate
+ this descriptor, so developers don't have to worry about directly
+ authoring or maintaining a separate XML metadata file.
+ </p>
+ <p>To serve as a quick reference for the developer, the rest of this page
+ will document these features (the API, along with the annotations)
+ which are considered the best practice for developing Mojos.</p>
+ </div>
+ <div class="section"><h2>API Documentation<a name="API_Documentation"></a></h2>
+ <div class="section"><h3>org.apache.maven.plugin.Mojo<a name="org.apache.maven.plugin.Mojo"></a></h3>
+ <p>This interface forms the contract required for Mojos to interact
+ with the Maven infrastructure. It features an
+ <tt>execute()</tt>
+ method, which triggers the Mojo's build-process behavior, and can
+ throw a
+ <tt>MojoExecutionException</tt>
+ if an error condition
+ occurs. See below for a discussion on proper use of this
+ <tt>Exception</tt>
+ class. Also included is the
+ <tt>setLog(..)</tt>
+ method, which simply allows Maven to inject a
+ logging mechanism which will allow the Mojo to communicate to the
+ outside world through standard Maven channels.
+ </p>
+ <div class="section"><div class="section"><div class="section"><h6>Method Summary:<a name="Method_Summary:"></a></h6>
+ <ul>
+ <li>
+ <tt>
+ void setLog( org.apache.maven.plugin.logging.Log )
+ </tt>
+ <p>Inject a standard Maven logging mechanism to allow this Mojo
+ to communicate events and feedback to the user.</p>
+ </li>
+ <li>
+ <tt>
+ void execute() throws org.apache.maven.plugin.MojoExecutionException
+ </tt>
+ <p>Perform whatever build-process behavior this Mojo implements.
+ This is the main trigger for the Mojo inside the Maven system,
+ and allows the Mojo to communicate fatal errors by throwing an
+ instance of <tt>MojoExecutionException</tt>.
+ </p>
+ <p>The
+ <tt>MojoExecutionException</tt> (and all error
+ conditions inside the Mojo) should be handled very carefully.
+ The simple wrapping of lower-level exceptions without providing
+ any indication of a user-friendly probable cause is strictly
+ discouraged. In fact, a much better course of action is to
+ provide error handling code (try/catch stanzas) for each
+ coherent step within the Mojo's execution. Developers are then
+ in a much better position to diagnose the cause of any error,
+ and provide user-friendly feedback in the message of the
+ <tt>MojoExecutionException</tt>.
+ </p>
+ </li>
+ </ul>
+ </div></div></div></div>
+ <div class="section"><h3>org.apache.maven.plugin.AbstractMojo<a name="org.apache.maven.plugin.AbstractMojo"></a></h3>
+ <p>Currently, this abstract base class simply takes care of managing
+ the Maven log for concrete derivations. In keeping with this, it
+ provides a
+ <tt>protected</tt>
+ method,
+ <tt>getLog():Log</tt>
+ ,
+ to furnish Log access to these concrete implementations.
+ </p>
+ <div class="section"><div class="section"><div class="section"><h6>Method Summary:<a name="Method_Summary:"></a></h6>
+ <ul>
+ <li>
+ <tt>
+ public void setLog( org.apache.maven.plugin.logging.Log )
+ </tt>
+ <p>
+ <b>[IMPLEMENTED]</b>
+ </p>
+ <p>Inject a standard Maven logging mechanism to allow this Mojo
+ to communicate events and feedback to the user.</p>
+ </li>
+ <li>
+ <tt>protected Log getLog()</tt>
+ <p>
+ <b>[IMPLEMENTED]</b>
+ </p>
+ <p>Furnish access to the standard Maven logging mechanism which
+ is managed in this base class.</p>
+ </li>
+ <li>
+ <tt>
+ void execute() throws org.apache.maven.plugin.MojoExecutionException
+ </tt>
+ <p>
+ <b>[ABSTRACT]</b>
+ </p>
+ <p>Perform whatever build-process behavior this Mojo implements.
+ See the documentation for
+ <tt>Mojo</tt>
+ above for more
+ information.
+ </p>
+ </li>
+ </ul>
+ </div></div></div></div>
+ <div class="section"><h3>org.apache.maven.plugin.logging.Log<a name="org.apache.maven.plugin.logging.Log"></a></h3>
+ <p>This interface supplies the API for providing feedback to the user
+ from the Mojo, using standard Maven channels. There should be no big
+ surprises here, although you may notice that the methods accept
+ <tt>java.lang.CharSequence</tt>
+ rather than
+ <tt>java.lang.String</tt>
+ . This is provided mainly as a
+ convenience, to enable developers to pass things like
+ <tt>StringBuffer</tt>
+ directly into the logger, rather than
+ formatting first by calling
+ <tt>toString()</tt>
+ .
+ </p>
+ <div class="section"><div class="section"><div class="section"><h6>Method Summary:<a name="Method_Summary:"></a></h6>
+ <ul>
+ <li>
+ <tt>void debug( java.lang.CharSequence )</tt>
+ <p>Send a message to the user in the
+ <b>debug</b>
+ error level.
+ </p>
+ </li>
+ <li>
+ <tt>
+ void debug( java.lang.CharSequence, java.lang.Throwable )
+ </tt>
+ <p>Send a message (and accompanying exception) to the user in the
+ <b>debug</b>
+ error level. The error's stacktrace will be output
+ when this error level is enabled.
+ </p>
+ </li>
+ <li>
+ <tt>void debug( java.lang.Throwable )</tt>
+ <p>Send an exception to the user in the
+ <b>debug</b>
+ error level.
+ The stack trace for this exception will be output when this
+ error level is enabled.
+ </p>
+ </li>
+ <li>
+ <tt>void info( java.lang.CharSequence )</tt>
+ <p>Send a message to the user in the
+ <b>info</b>
+ error level.
+ </p>
+ </li>
+ <li>
+ <tt>
+ void info( java.lang.CharSequence, java.lang.Throwable )
+ </tt>
+ <p>Send a message (and accompanying exception) to the user in the
+ <b>info</b>
+ error level. The error's stacktrace will be output
+ when this error level is enabled.
+ </p>
+ </li>
+ <li>
+ <tt>void info( java.lang.CharSequence )</tt>
+ <p>Send an exception to the user in the
+ <b>info</b>
+ error level.
+ The stack trace for this exception will be output when this
+ error level is enabled.
+ </p>
+ </li>
+ <li>
+ <tt>void warn( java.lang.CharSequence )</tt>
+ <p>Send a message to the user in the
+ <b>warn</b>
+ error level.
+ </p>
+ </li>
+ <li>
+ <tt>
+ void warn( java.lang.CharSequence, java.lang.Throwable )
+ </tt>
+ <p>Send a message (and accompanying exception) to the user in the
+ <b>warn</b>
+ error level. The error's stacktrace will be output
+ when this error level is enabled.
+ </p>
+ </li>
+ <li>
+ <tt>void warn( java.lang.CharSequence )</tt>
+ <p>Send an exception to the user in the
+ <b>warn</b>
+ error level.
+ The stack trace for this exception will be output when this
+ error level is enabled.
+ </p>
+ </li>
+ <li>
+ <tt>void error( java.lang.CharSequence )</tt>
+ <p>Send a message to the user in the
+ <b>error</b>
+ error level.
+ </p>
+ </li>
+ <li>
+ <tt>
+ void error( java.lang.CharSequence, java.lang.Throwable )
+ </tt>
+ <p>Send a message (and accompanying exception) to the user in the
+ <b>error</b>
+ error level. The error's stacktrace will be output
+ when this error level is enabled.
+ </p>
+ </li>
+ <li>
+ <tt>void error( java.lang.CharSequence )</tt>
+ <p>Send an exception to the user in the
+ <b>error</b>
+ error level.
+ The stack trace for this exception will be output when this
+ error level is enabled.
+ </p>
+ </li>
+ </ul>
+ </div></div></div></div>
+ </div>
+ <div class="section"><h2>The Descriptor and Annotations<a name="The_Descriptor_and_Annotations"></a></h2>
+ <p>In addition to the normal Java requirements in terms of interfaces
+ and/or abstract base classes which need to be implemented, a plugin
+ descriptor must accompany these classes inside the plugin jar. This
+ descriptor file is used to provide metadata about the parameters and
+ other component requirements for a set of Mojos so that Maven can
+ initialize the Mojo and validate its configuration before executing
+ it. As such, the plugin descriptor has a certain set of information
+ that is required for each Mojo specification to be valid, as well as
+ requirements for the overall plugin descriptor itself.</p>
+ <p>NOTE: In the following discussion, bolded items are the descriptor's
+ element name along with a Javadoc annotation (if applicable) supporting
+ that piece of the plugin descriptor. A couple of examples are:
+ <b>someElement
+ (@annotation parameterName="parameterValue")</b>
+ or
+ <b>someOtherElement (@annotation <rawAnnotationValue>)</b>
+ .
+ </p>
+ <p><b>NOTE:</b> since maven-plugin-plugin 3.0 is now possible to use java1.5 annotations.
+ See <a class="externalLink" href="http://maven.apache.org/plugin-tools/maven-plugin-plugin/examples/using-annotations.html">Using annotations.</a>
+ </p>
+ <p>The plugin descriptor must be provided in a jar resource with the
+ path:
+ <tt>META-INF/maven/plugin.xml</tt>
+ , and it must contain the
+ following:
+ </p>
+ <table border="0" class="bodyTable">
+ <tr class="a">
+ <th>Descriptor Element</th>
+ <th>Required?</th>
+ <th>Notes</th>
+ </tr>
+ <tr class="b">
+ <td>mojos</td>
+ <td>Yes</td>
+ <td>Descriptors for each Mojo provided by the plugin, each inside a
+ <b>mojo</b>
+ sub-element. Mojo descriptors are covered in detail
+ below. Obviously, a plugin without any declared Mojos doesn't
+ make sense, so the
+ <b>mojos</b>
+ element is required, along with
+ at least one
+ <b>mojo</b>
+ sub-element.
+ </td>
+ </tr>
+ <tr class="a">
+ <td>dependencies</td>
+ <td>Yes</td>
+ <td>A set of dependencies which the plugin requires in order to
+ function. Each dependency is provided inside a
+ <b>dependency</b>
+ sub-element. Dependency specifications are covered below. Since
+ all plugins must have a dependency on
+ <tt>maven-plugin-api</tt>
+ , this element is effectively
+ required.
+ <i>Using the plugin toolset, these dependencies can be
+ extracted from the POM's dependencies.</i>
+ </td>
+ </tr>
+ </table>
+ <p>Each Mojo specified inside a plugin descriptor must provide the
+ following (annotations specified here are at the class level):</p>
+ <table border="0" class="bodyTable">
+ <!-- Annotations listed by specific, autodetect and Javadoc, all alphabetical -->
+ <tr class="a">
+ <th>Descriptor Element</th>
+ <th>Annotation</th>
+ <th>Required?</th>
+ <th>Notes</th>
+ </tr>
+ <tr class="b">
+ <td>aggregator</td>
+ <td>@aggregator</td>
+ <td>No</td>
+ <td>Flags this Mojo to run it in a multi module way, i.e. aggregate the build with the set of
+ projects listed as modules.</td>
+ </tr>
+ <tr class="a">
+ <td>configurator</td>
+ <td>@configurator <roleHint></td>
+ <td>No</td>
+ <td>The configurator type to use when injecting parameter values into this Mojo. The value is
+ normally deduced from the Mojo's implementation language, but can be specified to allow a
+ custom ComponentConfigurator implementation to be used. <i>NOTE: This will only be used in
+ very special cases, using a highly controlled vocabulary of possible values. (Elements
+ like this are why it's a good idea to use the descriptor tools.)</i>
+ </td>
+ </tr>
+ <tr class="b">
+ <td>execute</td>
+ <td>
+ <ul>
+ <li>@execute phase="<phaseName>"
+ lifecycle="<lifecycleId>"</li>
+ <li>@execute phase="<phaseName>"</li>
+
+ <li>@execute goal="<goalName>"</li>
+ </ul>
+ </td>
+ <td>No</td>
+ <td>When this goal is invoked, it will first invoke a parallel lifecycle, ending at the given
+ phase. If a goal is provided instead of a phase, that goal will be executed in isolation.
+ The execution of either will not affect the current project, but instead make available the
+ <tt>${executedProject}</tt> expression if required. An alternate lifecycle can also be
+ provided: for more information see the documentation on the
+ <a href="../guides/introduction/introduction-to-the-lifecycle.html">build lifecycle</a>.</td>
+ </tr>
+ <tr class="a">
+ <td>executionStrategy</td>
+ <td>@executionStrategy <strategy></td>
+ <td>No</td>
+ <td>Specify the execution strategy. <i>NOTE: Currently supports <b>once-per-session</b>,
+ <b>always</b>.</i>
+ </td>
+ </tr>
+ <tr class="b">
+ <td>goal</td>
+ <td>@goal <goalName></td>
+ <td>Yes</td>
+ <td>The name for the Mojo that users will reference from the command line to execute the Mojo
+ directly, or inside a POM in order to provide Mojo-specific configuration.</td>
+ </tr>
+ <tr class="a">
+ <td>inheritByDefault</td>
+ <td>@inheritByDefault <true|false></td>
+ <td>No. Default: <tt>true</tt></td>
+ <td>Specify that the Mojo is inherited.</td>
+ </tr>
+ <tr class="b">
+ <td>instantiationStrategy </td>
+ <td>@instantiationStrategy <per-lookup></td>
+ <td>No. Default: <tt>per-lookup</tt></td>
+ <td>Specify the instantiation strategy.</td>
+ </tr>
+ <tr class="a">
+ <td>phase</td>
+ <td>@phase <phaseName></td>
+ <td>No</td>
+ <td>
+ Defines a default phase to bind a mojo execution to if the user does not explicitly set a phase in the POM.
+ <i>Note:</i> This annotation will not automagically make a mojo run when the plugin declaration is added
+ to the POM. It merely enables the user to omit the <tt><phase></tt> element from the surrounding
+ <tt><execution></tt> element.
+ </td>
+ </tr>
+ <tr class="b">
+ <td>requiresDependencyResolution</td>
+ <td>@requiresDependencyResolution <requiredClassPath></td>
+ <td>No</td>
+ <td>
+ Flags this Mojo as requiring the dependencies in the specified class path to be resolved before it can
+ execute. The matrix below illustrates which values for <i><requiredClassPath></i> (first column) are
+ supported and which dependency scopes (first row) they will request to resolve:
+ <table border="0" class="bodyTable">
+ <tr class="a">
+ <td></td>
+ <td>system</td>
+ <td>provided</td>
+ <td>compile</td>
+ <td>runtime</td>
+ <td>test</td>
+ </tr>
+ <tr class="b">
+ <td><tt>compile</tt></td>
+ <td>X</td>
+ <td>X</td>
+ <td>X</td>
+ <td>-</td>
+ <td>-</td>
+ </tr>
+ <tr class="a">
+ <td><tt>runtime</tt></td>
+ <td>-</td>
+ <td>-</td>
+ <td>X</td>
+ <td>X</td>
+ <td>-</td>
+ </tr>
+ <tr class="b">
+ <td><tt>compile+runtime</tt> (since Maven 3.0)</td>
+ <td>X</td>
+ <td>X</td>
+ <td>X</td>
+ <td>X</td>
+ <td>-</td>
+ </tr>
+ <tr class="a">
+ <td><tt>test</tt></td>
+ <td>X</td>
+ <td>X</td>
+ <td>X</td>
+ <td>X</td>
+ <td>X</td>
+ </tr>
+ </table>
+ If this annotation is present but no scope is specified, the scope defaults to <tt>runtime</tt>. If
+ the annotation is not present at all, the mojo must not make any assumptions about the artifacts associated
+ with a Maven project.
+ </td>
+ </tr>
+ <tr class="a">
+ <td>requiresDependencyCollection</td>
+ <td>@requiresDependencyCollection <requiredClassPath></td>
+ <td>No</td>
+ <td>
+ Flags this mojo as requiring information about the dependencies that would make up the specified class path.
+ As the name suggests, this annotation is similar to <tt>@requiresDependencyResolution</tt> and supports
+ the same values for <i><requiredClassPath></i>. The important difference is that this annotation will
+ not resolve the files for the dependencies, i.e. the artifacts associated with a Maven project can lack a
+ file. As such, this annotation is meant for mojos that only want to analyze the set of transitive
+ dependencies, in particular during early lifecycle phases where full dependency resolution might fail due to
+ projects which haven't been built yet. A mojo may use both this annotation and <tt>@requiresDependencyResolution</tt>
+ at the same time. The resolution state of any dependency that is collected but not requested to be resolved
+ is undefined. Since Maven 3.0.
+ </td>
+ </tr>
+ <tr class="b">
+ <td>requiresDirectInvocation</td>
+ <td>@requiresDirectInvocation <true|false></td>
+ <td>No. Default: <tt>false</tt></td>
+ <td>Flags this Mojo to be invoke directly.</td>
+ </tr>
+ <tr class="a">
+ <td>requiresOnline</td>
+ <td>@requiresOnline <true|false></td>
+ <td>No. Default: <tt>false</tt></td>
+ <td>Flags this Mojo to require online mode for its operation.</td>
+ </tr>
+ <tr class="b">
+ <td>requiresProject</td>
+ <td>@requiresProject <true|false></td>
+ <td>No. Default: <tt>true</tt></td>
+ <td>Flags this Mojo to run inside of a project.</td>
+ </tr>
+ <tr class="a">
+ <td>requiresReports</td>
+ <td>@requiresReports <true|false></td>
+ <td>No. Default: <tt>false</tt></td>
+ <td>Flags this Mojo to require reports. Unsupported since Maven 3.0.</td>
+ </tr>
+ <tr class="b">
+ <td>threadSafe</td>
+ <td>@threadSafe <true|false></td>
+ <td>No. Default: <tt>false</tt></td>
+ <td>
+ Marks this mojo as being thread-safe, i.e. the mojo safely supports concurrent execution during parallel builds.
+ Mojos without this annotation will make Maven output a warning when used during a parallel build session.
+ The short-hand notation <tt>@threadSafe</tt> without a tag value is equivalent to <tt>@threadSafe true</tt>.
+ Since Maven 3.0.
+ </td>
+ </tr>
+
+ <!-- Autodetect -->
+ <tr class="a">
+ <td>description</td>
+ <td>none (detected)</td>
+ <td>No</td>
+ <td>The description of this Mojo's functionality. <i>Using the toolset, this will be the
+ class-level Javadoc description provided. NOTE: While this is not a required part of the
+ Mojo specification, it SHOULD be provided to enable future tool support for browsing, etc.
+ and for clarity.</i>
+ </td>
+ </tr>
+ <tr class="b">
+ <td>implementation</td>
+ <td>none (detected)</td>
+ <td>Yes</td>
+ <td>The Mojo's fully-qualified class name (or script path in the case of non-Java Mojos).</td>
+ </tr>
+ <tr class="a">
+ <td>language</td>
+ <td>none (detected)</td>
+ <td>No. Default: <tt>java</tt></td>
+ <td>The implementation language for this Mojo (Java, beanshell, etc.).</td>
+ </tr>
+
+ <!-- Javadoc -->
+ <tr class="b">
+ <td>deprecated</td>
+ <td>@deprecated <deprecated-text></td>
+ <td>No</td>
+ <td>Specify the version when the Mojo was deprecated to the API. Similar to Javadoc deprecated.
+ This will trigger a warning when a user tries to configure a parameter
+ marked as deprecated.</td>
+ </tr>
+ <tr class="a">
+ <td>since</td>
+ <td>@since <since-text></td>
+ <td>No</td>
+ <td>Specify the version when the Mojo was added to the API. Similar to Javadoc since.</td>
+ </tr>
+ </table>
+ <p>Each Mojo specifies the parameters that it expects in order to work.
+ These parameters are the Mojo's link to the outside world, and
+ will be satisfied through a combination of POM/project values, plugin
+ configurations (from the POM and configuration defaults), and System
+ properties.</p>
+ <p>NOTE[1]: For this discussion on Mojo parameters, a single
+ annotation may span multiple elements in the descriptor's specification
+ for that parameter. Duplicate annotation declarations in this section
+ will be used to detail each parameter of an annotation separately.</p>
+ <p>NOTE[2]: In many cases, simply annotating a Mojo field with
+ <b>@parameter</b>
+ will be enough to allow injection of a value for that
+ parameter using POM configuration elements. The discussion below
+ shows advanced usage for this annotation, along with others.
+ </p>
+ <p>Each parameter for a Mojo must be specified in the
+ plugin descriptor as follows:</p>
+ <table border="0" class="bodyTable">
+ <!-- Annotations listed by specific, autodetect and Javadoc, all alphabetical -->
+ <tr class="a">
+ <th>Descriptor Element</th>
+ <th>Annotation</th>
+ <th>Required?</th>
+ <th>Notes</th>
+ </tr>
+ <tr class="b">
+ <td>alias</td>
+ <td>@parameter alias="myAlias"</td>
+ <td>No</td>
+ <td>Specifies an alias which can be used to configure this parameter from the POM. This is
+ primarily useful to improve user-friendliness, where Mojo field names are not intuitive to
+ the user or are otherwise not conducive to configuration via the POM.</td>
+ </tr>
+ <tr class="a">
+ <td>configuration</td>
+ <td>@component role="..." roleHint="..."</td>
+ <td>No</td>
+ <td>Populates the field with an instance of a Plexus component. This is like declaring a
+ <i>requirement</i> in a Plexus component. The default requirement will have a role equal
+ to the declared type of the field, and will use the role hint "default". You can customise
+ either of these by providing a <tt>role</tt> and/or <tt>roleHint</tt> parameter.
+ <i>e.g.</i>
+ <tt>@component role="org.apache.maven.artifact.ArtifactHandler"
+ roleHint="ear"</tt>. <b>Note:</b> This is identical to the deprecated
+ form of parameter: <tt>@parameter
+ expression="${component.yourpackage.YourComponentClass#roleHint}"</tt>. </td>
+ </tr>
+ <tr class="b">
+ <td>configuration</td>
+ <td>@parameter expression="${aSystemProperty}"
+ default-value="${anExpression}"</td>
+ <td>No</td>
+ <td>Specifies the expressions used to calculate the value to be injected into this parameter of
+ the Mojo at buildtime. The expression given by <tt>default-value</tt> is commonly used to refer to
+ specific elements in the POM, such as <tt>${project.resources}</tt>, which refers to the list of
+ resources meant to accompany the classes in the resulting JAR file. Of course, the default value need not
+ be an expression but can also be a simple constant like <tt>true</tt> or <tt>1.5</tt>. And for
+ parameters of type <tt>String</tt> one can mix expressions with literal values, e.g.
+ <tt>${project.artifactId}-${project.version}-special</tt>. The system property given by <tt>expression</tt>
+ enables users to override the default value from the command line via <tt>-DaSystemProperty=value</tt>.
+ <i>NOTE: If neither <tt>default-value</tt> nor <tt>expression</tt> are specified, the parameter can
+ only be configured from the POM. The use of '${' and '}' is required to delimit actual expressions
+ which may be evaluated.</i>
+ </td>
+ </tr>
+ <tr class="a">
+ <td>editable</td>
+ <td>@readonly</td>
+ <td>No</td>
+ <td>Specifies that this parameter cannot be configured directly by the user (as in the case of
+ POM-specified configuration). This is useful when you want to force the user to use common
+ POM elements rather than plugin configurations, as in the case where you want to use the
+ artifact's final name as a parameter. In this case, you want the user to modify
+ <build><finalName/></build> rather than specifying
+ a value for finalName directly in the plugin configuration section. It is also useful to
+ ensure that - for example - a List-typed parameter which expects items of type Artifact
+ doesn't get a List full of Strings. <i>NOTE: Specification of this annotation flags the
+ parameter as non-editable; there is no true/false value.</i>
+ </td>
+ </tr>
+ <tr class="b">
+ <td>required</td>
+ <td>@required</td>
+ <td>No</td>
+ <td>Whether this parameter is required for the Mojo to function. This is used to validate the
+ configuration for a Mojo before it is injected, and before the Mojo is executed from some
+ half-state. <i>NOTE: Specification of this annotation flags the parameter as required; there
+ is no true/false value.</i>
+ </td>
+ </tr>
+
+ <!-- Autodetect -->
+ <tr class="a">
+ <td>description</td>
+ <td>none (detected)</td>
+ <td>No</td>
+ <td>The description of this parameter's use inside the Mojo. <i>Using the toolset, this is
+ detected as the Javadoc description for the field. NOTE: While this is not a required part
+ of the parameter specification, it SHOULD be provided to enable future tool support for
+ browsing, etc. and for clarity.</i>
+ </td>
+ </tr>
+ <tr class="b">
+ <td>name</td>
+ <td>none (detected)</td>
+ <td>Yes</td>
+ <td>The name of the parameter, to be used in configuring this parameter from the Mojo's
+ declared defaults (discussed below) or from the POM. <i>Using the toolset, this is detected
+ as the Java field name.</i>
+ </td>
+ </tr>
+ <tr class="a">
+ <td>type</td>
+ <td>none (detected)</td>
+ <td>Yes</td>
+ <td>The Java type for this parameter. This is used to validate the result of any expressions
+ used to calculate the value which should be injected into the Mojo for this parameter.
+ <i>Using the toolset, this is detected as the class of the Java field corresponding to
+ this parameter.</i>
+ </td>
+ </tr>
+
+ <!-- Javadoc -->
+ <tr class="b">
+ <td>deprecated</td>
+ <td>@deprecated <deprecated-text></td>
+ <td>No</td>
+ <td>Specify the version when the Mojo was deprecated to the API. Similar to Javadoc deprecated.
+ This will trigger a warning when a user tries to configure a parameter
+ marked as deprecated.</td>
+ </tr>
+ <tr class="a">
+ <td>since</td>
+ <td>@since <since-text></td>
+ <td>No</td>
+ <td>Specify the version when the Mojo was added to the API. Similar to Javadoc since.</td>
+ </tr>
+ </table>
+ <p>The final component of a plugin descriptor is the dependencies. This
+ enables the plugin to function independently of its POM (or at least
+ to declare the libraries it needs to run). Dependencies are taken from
+ the
+ <b>runtime</b>
+ scope of the plugin's calculated dependencies (from
+ the POM). Dependencies are specified in exactly the same manner as in
+ the POM, except for the <scope> element (all dependencies in the
+ plugin descriptor are assumed to be runtime, because this is a
+ runtime profile for the plugin).
+ </p>
+ </div>
+ <div class="section"><h2>Plugin Tools<a name="Plugin_Tools"></a></h2>
+ <p>By now, we've mentioned the plugin tools several times without telling
+ you what they are or how to use them. Instead of manually writing (and
+ maintaining) the metadata detailed above, Maven ships with some
+ tools to aid in this task. In fact, the only thing a plugin developer
+ needs to do is declare his project to be a plugin from within the POM.
+ Once this is done, Maven will call the appropriate descriptor
+ generators, etc. to produce an artifact that is ready for use within
+ Maven builds. Optional metadata can be injected via Javadoc annotation
+ (and possibly JDK5 annotations in the future) as described above,
+ enabling richer interactions between the Mojo and the user. The
+ section below describes the changes to the POM which are necessary to
+ create plugin artifacts.</p>
+ </div>
+ <div class="section"><h2>Project Descriptor (POM) Requirements<a name="Project_Descriptor_POM_Requirements"></a></h2>
+ <p>From the POM, Maven plugin projects look quite similar to any other
+ project. For pure Java plugins, the differences are even smaller than
+ for script-based plugins. The following details the POM elements
+ which are necessary to build a Maven plugin artifact.</p>
+ <table border="0" class="bodyTable">
+ <tr class="a">
+ <th>POM Element</th>
+ <th>Required for Java Mojos?</th>
+ <th>Sample Declaration</th>
+ <th>Notes</th>
+ </tr>
+ <tr class="b">
+ <td>packaging</td>
+ <td>Yes</td>
+ <td>
+ <tt><packaging>
+ maven-plugin
+ </packaging></tt>
+ </td>
+ <td>The POM must declare a packaging element which describes this
+ project as a Maven plugin project.</td>
+ </tr>
+ <tr class="a">
+ <td>scriptSourceDirectory</td>
+ <td>No</td>
+ <td>
+ <tt><scriptSourceDirectory>
+ src/main/scripts
+ </scriptSourceDirectory></tt>
+ </td>
+ <td>In the case of script-based Mojos (which are not covered in
+ detail within this document), the POM must include an additional
+ element to distinguish script sources from (optional) Java
+ supporting classes. This element is <tt>scriptSourceDirectory</tt>,
+ inside the <tt>build</tt> section. This directory is included in the list
+ of resources which accompany any compiled code in the resulting
+ artifact. It is specified separately from the resources in the
+ build section to denote its special status as an alternate source
+ directory for scripts.</td>
+ </tr>
+ </table>
+ <p>After making the changes above, the developer can simply call</p>
+ <div class="source"><pre>mvn install</pre></div>
+ <p>
+ to install the plugin to
+ the local repository. (Any of the other standard lifecycle targets like
+ package, deploy, etc. are also available in like fashion.)
+ </p>
+ </div>
+ <div class="section"><h2>IDE integration<a name="IDE_integration"></a></h2>
+ <p>If you're using JetBrains IntelliJ IDEA to develop your plugin,
+ you can use the following to configure the javadoc annotations as live
+ templates.</p>
+ <ol style="list-style-type: decimal">
+ <li>Download <a href="./maven.xml">this file</a>,
+ and place it in <tt>$USER_HOME/.IntelliJIdea/config/templates</tt></li>
+ <li>(re)startup IntelliJ IDEA (templates are loaded on startup)</li>
+ <li>add the following list to Settings -> IDE -> Errors -> General
+ -> Unknown javadoc tags -> Additional javadoc tags
+ <ul>
+ <li>aggregator, execute, goal, phase, requiresDirectInvocation,
+ requiresProject, requiresReports, requiresOnline, parameter,
+ component, required, readonly</li>
+ </ul>
+ </li>
+ </ol>
+ </div>
+ <div class="section"><h2>Resources<a name="Resources"></a></h2>
+ <p>This section simply gives a listing of pointers for more
+ information.</p>
+ <ul>
+ <li>QDox Project (Javadoc annotations) [
+ <a class="externalLink" href="http://qdox.codehaus.org">link</a>
+ ]
+ </li>
+ <li>Plexus Project (Plexus container) [
+ <a class="externalLink" href="http://plexus.codehaus.org/plexus-containers/">link</a>
+ ]
+ </li>
+ <li>Maven Plugin API [
+ <a class="externalLink" href="http://maven.apache.org/ref/current/maven-plugin-api/apidocs/index.html">link</a>
+ ]
+ </li>
+ <li>MojoDescriptor API [
+ <a class="externalLink" href="http://maven.apache.org/ref/current/maven-plugin-api/apidocs/org/apache/maven/plugin/descriptor/MojoDescriptor.html">link</a>
+ ]
+ </li>
+ </ul>
+ </div>
+
+
+ </div>
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ <div id="footer">
+ <div class="xright">
+ © 2002-2012
+ The Apache Software Foundation
+
+ - <a href="http://maven.apache.org/privacy-policy.html">Privacy Policy</a>.
+ Apache Maven, Maven, Apache, the Apache feather logo, and the Apache Maven project logos are trademarks of The Apache Software Foundation.
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ </body>
+</html>
Added: websites/staging/maven/trunk/content/developers/release/.htaccess
==============================================================================
--- websites/staging/maven/trunk/content/developers/release/.htaccess (added)
+++ websites/staging/maven/trunk/content/developers/release/.htaccess Mon Dec 10 08:17:24 2012
@@ -0,0 +1,2 @@
+RedirectMatch permanent (.*)/developers/committer-testing-plugins.html $1/plugin-developers/plugin-testing.html
+RedirectMatch permanent (.*)/developers/committer-documentation-plugins.html $1/plugin-developers/plugin-documenting.html
Added: websites/staging/maven/trunk/content/developers/release/maven-core-release.html
==============================================================================
--- websites/staging/maven/trunk/content/developers/release/maven-core-release.html (added)
+++ websites/staging/maven/trunk/content/developers/release/maven-core-release.html Mon Dec 10 08:17:24 2012
@@ -0,0 +1,253 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<!--
+ | Generated by Apache Maven Doxia at Dec 10, 2012
+ | Rendered using Apache Maven Stylus Skin 1.5
+-->
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <title>Maven - Releasing Maven</title>
+ <style type="text/css" media="all">
+ @import url("../../css/maven-base.css");
+ @import url("../../css/maven-theme.css");
+ @import url("../../css/site.css");
+ </style>
+ <link rel="stylesheet" href="../../css/print.css" type="text/css" media="print" />
+ <meta name="author" content="Jason van Zyl
+Olivier Lamy" />
+ <meta name="Date-Creation-yyyymmdd" content="20120911" />
+ <meta name="Date-Revision-yyyymmdd" content="20121210" />
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+
+<script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script>
+
+<script type="text/javascript">_uacct = "UA-140879-1";
+ urchinTracker();</script>
+ </head>
+ <body class="composite">
+ <div id="banner">
+ <a href="../.././" id="bannerLeft">
+ <img src="../../images/apache-maven-project-2.png" alt="" />
+ </a>
+ <span id="bannerRight">
+ <img src="../../images/maven-logo-2.gif" alt="" />
+ </span>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="breadcrumbs">
+
+ <div class="xleft">
+ <a href="http://www.apache.org/" class="externalLink">Apache</a>
+ >
+ <a href="../../index.html">Maven</a>
+ >
+ Releasing Maven
+ </div>
+ <div class="xright">
+ Last Published: 2012-12-10
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="leftColumn">
+ <div id="navcolumn">
+
+ <h5>Main</h5>
+ <ul>
+ <li class="none">
+ <a href="../../index.html">Welcome</a>
+ </li>
+ </ul>
+ <h5>Get Maven</h5>
+ <ul>
+ <li class="none">
+ <a href="../../download.html">Download</a>
+ </li>
+ <li class="none">
+ <a href="../../docs/3.0.4/release-notes.html">Release Notes (3.0.4)</a>
+ </li>
+ <li class="none">
+ <a href="../../docs/2.2.1/release-notes.html">Release Notes (2.2.1)</a>
+ </li>
+ <li class="none">
+ <a href="../../docs/2.0.11/release-notes.html">Release Notes (2.0.11)</a>
+ </li>
+ <li class="none">
+ <a href="../../license.html">License</a>
+ </li>
+ </ul>
+ <h5>IDE Integration</h5>
+ <ul>
+ <li class="none">
+ <a href="../../eclipse-plugin.html">Eclipse</a>
+ </li>
+ <li class="none">
+ <a href="../../netbeans-module.html">NetBeans</a>
+ </li>
+ </ul>
+ <h5>About Maven</h5>
+ <ul>
+ <li class="none">
+ <a href="../../what-is-maven.html">What is Maven?</a>
+ </li>
+ <li class="none">
+ <a href="../../maven-features.html">Features</a>
+ </li>
+ <li class="none">
+ <a href="../../general.html">FAQ (official)</a>
+ </li>
+ <li class="none">
+ <a href="http://docs.codehaus.org/display/MAVENUSER/FAQs-1" class="externalLink">FAQ (unofficial)</a>
+ </li>
+ </ul>
+ <h5>Documentation</h5>
+ <ul>
+ <li class="none">
+ <a href="../../plugins/index.html">Maven Plugins</a>
+ </li>
+ <li class="none">
+ <a href="../../guides/index.html">Index (category)</a>
+ </li>
+ <li class="none">
+ <a href="../../run-maven/index.html">Running Maven</a>
+ </li>
+ <li class="collapsed">
+ <a href="../../users/index.html">User Centre</a>
+ </li>
+ <li class="collapsed">
+ <a href="../../plugin-developers/index.html">Plugin Developer Centre</a>
+ </li>
+ <li class="none">
+ <a href="../../repository/index.html">Maven Repository Centre</a>
+ </li>
+ <li class="none">
+ <a href="../../developers/index.html">Maven Developer Centre</a>
+ </li>
+ <li class="none">
+ <a href="../../articles.html">Books and Resources</a>
+ </li>
+ <li class="none">
+ <a href="http://docs.codehaus.org/display/MAVENUSER/Home" class="externalLink">Wiki</a>
+ </li>
+ </ul>
+ <h5>Community</h5>
+ <ul>
+ <li class="none">
+ <a href="../../community.html">Community Overview</a>
+ </li>
+ <li class="none">
+ <a href="../../guides/development/guide-helping.html">How to Contribute</a>
+ </li>
+ <li class="none">
+ <a href="../../guides/mini/guide-maven-evangelism.html">Maven Repository</a>
+ </li>
+ <li class="none">
+ <a href="../../users/getting-help.html">Getting Help</a>
+ </li>
+ <li class="none">
+ <a href="../../issue-tracking.html">Issue Tracking</a>
+ </li>
+ <li class="none">
+ <a href="../../source-repository.html">Source Repository</a>
+ </li>
+ <li class="none">
+ <a href="../../team-list.html">The Maven Team</a>
+ </li>
+ </ul>
+ <h5>Project Documentation</h5>
+ <ul>
+ <li class="collapsed">
+ <a href="../../project-info.html">Project Information</a>
+ </li>
+ </ul>
+ <h5>Maven Projects</h5>
+ <ul>
+ <li class="none">
+ <a href="../../ant-tasks/index.html">Ant Tasks</a>
+ </li>
+ <li class="none">
+ <a href="../../archetype/index.html">Archetype</a>
+ </li>
+ <li class="none">
+ <a href="../../doxia/index.html">Doxia</a>
+ </li>
+ <li class="none">
+ <a href="../../jxr/index.html">JXR</a>
+ </li>
+ <li class="none">
+ <a href="../../maven-1.x/index.html">Maven 1.x</a>
+ </li>
+ <li class="none">
+ <a href="../../index.html">Maven 2 & 3</a>
+ </li>
+ <li class="none">
+ <a href="../../pom/index.html">Parent POMs</a>
+ </li>
+ <li class="none">
+ <a href="../../plugins/index.html">Plugins</a>
+ </li>
+ <li class="none">
+ <a href="../../plugin-tools/index.html">Plugin Tools</a>
+ </li>
+ <li class="none">
+ <a href="../../scm/index.html">SCM</a>
+ </li>
+ <li class="none">
+ <a href="../../shared/index.html">Shared Components</a>
+ </li>
+ <li class="none">
+ <a href="../../skins/index.html">Skins</a>
+ </li>
+ <li class="none">
+ <a href="../../surefire/index.html">Surefire</a>
+ </li>
+ <li class="none">
+ <a href="../../wagon/index.html">Wagon</a>
+ </li>
+ </ul>
+ <h5>ASF</h5>
+ <ul>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/how-it-works.html" class="externalLink">How Apache Works</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/" class="externalLink">Foundation</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/sponsorship.html" class="externalLink">Sponsoring Apache</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/thanks.html" class="externalLink">Thanks</a>
+ </li>
+ </ul>
+ <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
+ <img alt="Built by Maven" src="../../images/logos/maven-feather.png"/>
+ </a>
+
+ </div>
+ </div>
+ <div id="bodyColumn">
+ <div id="contentBox">
+ <!-- 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. --><div class="section"><h2>Releasing Maven<a name="Releasing_Maven"></a></h2><p>Maven differs slightly
in its release process due to several extra steps and this need to be publish via Apache svnpubsub.</p><p>The goal is to commit candidate release to svn tree https://dist.apache.org/repos/dist/dev/maven/maven-3/$VERSION. Then once the vote passed svn move to https://dist.apache.org/repos/dist/release/maven/maven-3/$VERSION.</p><p>The tree directory is:</p><ul><li>https://dist.apache.org/repos/dist/release/maven/maven-3/$VERSION/binaries</li><li>https://dist.apache.org/repos/dist/release/maven/maven-3/$VERSION/source</li></ul><div class="section"><h3>Produce Release Candidates<a name="Produce_Release_Candidates"></a></h3><p>For non-alpha/beta releases, release candidates are produced before the actual release.</p><p>Checkout https://dist.apache.org/repos/dist/dev/maven/maven-3 then create the necessary directory tree.</p><p>Copy the binaries and src-tar.gz with their md5/asc to the created directories.</p><p>To produce a release candidate, follow the first seven steps only f
rom the following procedure:</p><ul><li><a href="./maven-project-release-procedure.html"> Maven Project Common Release Procedure</a></li></ul><p>The version used should be the eventual version with -RC1, -RC2, etc. appended.</p><p>After producing the RC, request that the developers test the release on the list. If a regression is found, a new release candidate is rolled.</p><p>After a reasonable time without regressions found, a wider audience may be polled if the release manager desires (for example, users@).</p><p>Once happy with a release candidate, the full release is performed, with the final version in place.</p></div><div class="section"><h3>Produce the Release<a name="Produce_the_Release"></a></h3><p>To produce a final release, the same process as for standard projects is followed:</p><ul><li><a href="./maven-project-release-procedure.html"> Maven Project Common Release Procedure</a></li></ul><p>Below describes the additional steps that need to be taken at the points
where the website are updated in those instructions.</p><div class="section"><h4>Update the DOAP Information<a name="Update_the_DOAP_Information"></a></h4><p>Edit <a class="externalLink" href="https://svn.apache.org/repos/asf/maven/maven-3/trunk/doap_Maven.rdf">https://svn.apache.org/repos/asf/maven/maven-3/trunk/doap_Maven.rdf</a> to list the new release.</p></div><div class="section"><h4>Update the Release Notes and Web Site<a name="Update_the_Release_Notes_and_Web_Site"></a></h4><p>Checkout <a class="externalLink" href="https://svn.apache.org/repos/asf/maven/site/trunk">https://svn.apache.org/repos/asf/maven/site/trunk</a>.</p><p>Note that release notes can be created and checked in, but other changes should not be checked in as it can be deployed 'live' at any time.</p><ul><li>For 2.0.x: update the <tt>versions2x</tt>, <tt>current20xVersion</tt> and <tt>current20xReleaseDate</tt> properties in <tt>pom.xml</tt></li><li>For 2.2.x: update the <tt>versions2x</tt>, <tt>curre
nt22xVersion</tt> and <tt>current22xReleaseDate</tt> properties in <tt>pom.xml</tt></li><li>For 3.x: update the <tt>versions3x</tt>, <tt>currentStableVersion</tt> and <tt>currentStableReleaseDate</tt> properties in <tt>pom.xml</tt></li></ul><p>Next, create the release notes:</p><ul><li>create docs/$version</li><li>populate docs/$version/release-notes.txt from JIRA</li><li>create docs/$version/release-notes.apt.vm (see other versions for an example)</li></ul><p>Only deploy the site once the release is present on the mirrors, and the reference documentation has been deployed to /ref/.</p></div><div class="section"><h4>Stage the Latest Documentation<a name="Stage_the_Latest_Documentation"></a></h4><p>Once the release is prepared, but before the release vote, the site needs to be staged.</p><ol style="list-style-type: decimal"><li>From the site checkout, stage the site (replacing $USER and $VERSION):<div class="source"><pre>mvn -Preporting site site:stage-deploy -DstagingSiteURL
=scp://people.apache.org/home/$USER/public_html/staged-sites/maven-$VERSION</pre></div><p><b>Note:</b> It requires Maven 2.1.0 or higher to successfully deploy to <tt>people.apache.org</tt> via SSH. Older Maven versions will fail due to <tt>com.jcraft.jsch.JSchException: Algorithm negotiation fail</tt>.</p><div class="source"><pre>http://people.apache.org/~USER/staged-sites/maven-VERSION</pre></div><p>Some developers have <a class="externalLink" href="http://www.nabble.com/site%3Astage-deploy-asks-for-a-password--tt15582961s177.html"> reported problems</a> with the <tt>site:stage-deploy</tt> goal. In that case, you can stage the site locally and upload it manually:</p><div class="source"><pre>mvn -Preporting site site:stage
+scp -r target/staging/people.apache.org/home/$USER/public_html/staged-sites/maven-$VERSION USER@people.apache.org:/home/$USER/public_html/staged-sites/maven-$VERSION</pre></div></li></ol></div><div class="section"><h4>Add New Version to ASF Distribution Directory<a name="Add_New_Version_to_ASF_Distribution_Directory"></a></h4><p>In addition to promoting the repository, the release archives should be moved to the release svnpubsub tree :</p><ul><li>svn mv https://dist.apache.org/repos/dist/dev/maven/maven-3/$VERSION https://dist.apache.org/repos/dist/release/maven/maven-3</li></ul></div><div class="section"><h4>Deploy the Current References<a name="Deploy_the_Current_References"></a></h4><p>The source code references and API docs need to be deployed before deploying the web site with the new version.</p><p>This is described in <a href="../website/deploy-maven-current-ref.html"> Deploying the Current References</a>.</p></div><div class="section"><h4>Deploying the Release Websi
te<a name="Deploying_the_Release_Website"></a></h4><p>Once both of the above have synced to the main site and a suitable number of mirrors, proceed to update the web site and produce the announcement.</p><p>Commit your changes and then deploy the main Maven site checked out earlier.</p><div class="source"><pre>mvn -Preporting clean site-deploy</pre></div></div><div class="section"><h4>Remove Old Versions from ASF Distribution Directory<a name="Remove_Old_Versions_from_ASF_Distribution_Directory"></a></h4><p>Next, any superceded releases should be removed from the above locations (after confirming that they exist in /www/archive.apache.org/dist/maven).</p></div><div class="section"><h4>Proceed with Announcement<a name="Proceed_with_Announcement"></a></h4><p>You can now proceed with the steps outlined after deploying the website on <a href="./maven-project-release-procedure.html"> Maven Project Common Release Procedure</a></p><p><b>Note:</b> For Maven core releases, the announ
cement is additionally sent to <tt>announce@apache.org</tt>. This is best done as a separate message to avoid cross-posting replies.</p></div></div></div>
+ </div>
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ <div id="footer">
+ <div class="xright">
+ © 2002-2012
+ The Apache Software Foundation
+
+ - <a href="http://maven.apache.org/privacy-policy.html">Privacy Policy</a>.
+ Apache Maven, Maven, Apache, the Apache feather logo, and the Apache Maven project logos are trademarks of The Apache Software Foundation.
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ </body>
+</html>
Added: websites/staging/maven/trunk/content/developers/release/maven-plugin-release.html
==============================================================================
--- websites/staging/maven/trunk/content/developers/release/maven-plugin-release.html (added)
+++ websites/staging/maven/trunk/content/developers/release/maven-plugin-release.html Mon Dec 10 08:17:24 2012
@@ -0,0 +1,256 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<!--
+ | Generated by Apache Maven Doxia at Dec 10, 2012
+ | Rendered using Apache Maven Stylus Skin 1.5
+-->
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <title>Maven - Releasing A Maven Plugin</title>
+ <style type="text/css" media="all">
+ @import url("../../css/maven-base.css");
+ @import url("../../css/maven-theme.css");
+ @import url("../../css/site.css");
+ </style>
+ <link rel="stylesheet" href="../../css/print.css" type="text/css" media="print" />
+ <meta name="author" content="Jason van Zyl" />
+ <meta name="Date-Creation-yyyymmdd" content="20101125" />
+ <meta name="Date-Revision-yyyymmdd" content="20121210" />
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+
+<script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script>
+
+<script type="text/javascript">_uacct = "UA-140879-1";
+ urchinTracker();</script>
+ </head>
+ <body class="composite">
+ <div id="banner">
+ <a href="../.././" id="bannerLeft">
+ <img src="../../images/apache-maven-project-2.png" alt="" />
+ </a>
+ <span id="bannerRight">
+ <img src="../../images/maven-logo-2.gif" alt="" />
+ </span>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="breadcrumbs">
+
+ <div class="xleft">
+ <a href="http://www.apache.org/" class="externalLink">Apache</a>
+ >
+ <a href="../../index.html">Maven</a>
+ >
+ Releasing A Maven Plugin
+ </div>
+ <div class="xright">
+ Last Published: 2012-12-10
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="leftColumn">
+ <div id="navcolumn">
+
+ <h5>Main</h5>
+ <ul>
+ <li class="none">
+ <a href="../../index.html">Welcome</a>
+ </li>
+ </ul>
+ <h5>Get Maven</h5>
+ <ul>
+ <li class="none">
+ <a href="../../download.html">Download</a>
+ </li>
+ <li class="none">
+ <a href="../../docs/3.0.4/release-notes.html">Release Notes (3.0.4)</a>
+ </li>
+ <li class="none">
+ <a href="../../docs/2.2.1/release-notes.html">Release Notes (2.2.1)</a>
+ </li>
+ <li class="none">
+ <a href="../../docs/2.0.11/release-notes.html">Release Notes (2.0.11)</a>
+ </li>
+ <li class="none">
+ <a href="../../license.html">License</a>
+ </li>
+ </ul>
+ <h5>IDE Integration</h5>
+ <ul>
+ <li class="none">
+ <a href="../../eclipse-plugin.html">Eclipse</a>
+ </li>
+ <li class="none">
+ <a href="../../netbeans-module.html">NetBeans</a>
+ </li>
+ </ul>
+ <h5>About Maven</h5>
+ <ul>
+ <li class="none">
+ <a href="../../what-is-maven.html">What is Maven?</a>
+ </li>
+ <li class="none">
+ <a href="../../maven-features.html">Features</a>
+ </li>
+ <li class="none">
+ <a href="../../general.html">FAQ (official)</a>
+ </li>
+ <li class="none">
+ <a href="http://docs.codehaus.org/display/MAVENUSER/FAQs-1" class="externalLink">FAQ (unofficial)</a>
+ </li>
+ </ul>
+ <h5>Documentation</h5>
+ <ul>
+ <li class="none">
+ <a href="../../plugins/index.html">Maven Plugins</a>
+ </li>
+ <li class="none">
+ <a href="../../guides/index.html">Index (category)</a>
+ </li>
+ <li class="none">
+ <a href="../../run-maven/index.html">Running Maven</a>
+ </li>
+ <li class="collapsed">
+ <a href="../../users/index.html">User Centre</a>
+ </li>
+ <li class="collapsed">
+ <a href="../../plugin-developers/index.html">Plugin Developer Centre</a>
+ </li>
+ <li class="none">
+ <a href="../../repository/index.html">Maven Repository Centre</a>
+ </li>
+ <li class="none">
+ <a href="../../developers/index.html">Maven Developer Centre</a>
+ </li>
+ <li class="none">
+ <a href="../../articles.html">Books and Resources</a>
+ </li>
+ <li class="none">
+ <a href="http://docs.codehaus.org/display/MAVENUSER/Home" class="externalLink">Wiki</a>
+ </li>
+ </ul>
+ <h5>Community</h5>
+ <ul>
+ <li class="none">
+ <a href="../../community.html">Community Overview</a>
+ </li>
+ <li class="none">
+ <a href="../../guides/development/guide-helping.html">How to Contribute</a>
+ </li>
+ <li class="none">
+ <a href="../../guides/mini/guide-maven-evangelism.html">Maven Repository</a>
+ </li>
+ <li class="none">
+ <a href="../../users/getting-help.html">Getting Help</a>
+ </li>
+ <li class="none">
+ <a href="../../issue-tracking.html">Issue Tracking</a>
+ </li>
+ <li class="none">
+ <a href="../../source-repository.html">Source Repository</a>
+ </li>
+ <li class="none">
+ <a href="../../team-list.html">The Maven Team</a>
+ </li>
+ </ul>
+ <h5>Project Documentation</h5>
+ <ul>
+ <li class="collapsed">
+ <a href="../../project-info.html">Project Information</a>
+ </li>
+ </ul>
+ <h5>Maven Projects</h5>
+ <ul>
+ <li class="none">
+ <a href="../../ant-tasks/index.html">Ant Tasks</a>
+ </li>
+ <li class="none">
+ <a href="../../archetype/index.html">Archetype</a>
+ </li>
+ <li class="none">
+ <a href="../../doxia/index.html">Doxia</a>
+ </li>
+ <li class="none">
+ <a href="../../jxr/index.html">JXR</a>
+ </li>
+ <li class="none">
+ <a href="../../maven-1.x/index.html">Maven 1.x</a>
+ </li>
+ <li class="none">
+ <a href="../../index.html">Maven 2 & 3</a>
+ </li>
+ <li class="none">
+ <a href="../../pom/index.html">Parent POMs</a>
+ </li>
+ <li class="none">
+ <a href="../../plugins/index.html">Plugins</a>
+ </li>
+ <li class="none">
+ <a href="../../plugin-tools/index.html">Plugin Tools</a>
+ </li>
+ <li class="none">
+ <a href="../../scm/index.html">SCM</a>
+ </li>
+ <li class="none">
+ <a href="../../shared/index.html">Shared Components</a>
+ </li>
+ <li class="none">
+ <a href="../../skins/index.html">Skins</a>
+ </li>
+ <li class="none">
+ <a href="../../surefire/index.html">Surefire</a>
+ </li>
+ <li class="none">
+ <a href="../../wagon/index.html">Wagon</a>
+ </li>
+ </ul>
+ <h5>ASF</h5>
+ <ul>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/how-it-works.html" class="externalLink">How Apache Works</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/" class="externalLink">Foundation</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/sponsorship.html" class="externalLink">Sponsoring Apache</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/thanks.html" class="externalLink">Thanks</a>
+ </li>
+ </ul>
+ <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
+ <img alt="Built by Maven" src="../../images/logos/maven-feather.png"/>
+ </a>
+
+ </div>
+ </div>
+ <div id="bodyColumn">
+ <div id="contentBox">
+ <!-- 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. --><div class="section"><h2>Releasing A Maven Plugin<a name="Releasing_A_Maven_Plugin"></a></h2><p>Rele
asing a Maven plugin is much the same as any other Maven project. The following guide walks through most of the steps:</p><ul><li><a href="./maven-project-release-procedure.html"> Maven Project Common Release procedure</a></li></ul><p>Note that plugins have particular conventions for deploying the project site. When encountered in the release process above, perform the following steps:</p><div class="section"><h3>Staging the latest documentation<a name="Staging_the_latest_documentation"></a></h3><p>Once the release is prepared, but before the release vote, the site needs to be staged.</p><p>The plugin parent POM is configured to stage the documentation in a "versioned" directory such as <tt>/plugins/maven-XXX-plugin-Y.Z</tt>.</p><ol style="list-style-type: decimal"><li>Stage the documentation for the current release version (not the new snapshot).<div class="source"><pre>cd target/checkout
+mvn site site:stage-deploy -Preporting</pre></div><p><b>Note:</b> It requires Maven 2.1.0 or higher to successfully deploy to <tt>people.apache.org</tt> via SSH. Older Maven versions will fail due to <tt>com.jcraft.jsch.JSchException: Algorithm negotiation fail</tt>.</p><p><b>Note:</b> You should verify the deployment of the site on the Maven website (you need to wait <a class="externalLink" href="http://www.apache.org/dev/project-site.html">the sync</a>).</p><div class="source"><pre>http://maven.apache.org/plugins/maven-XXX-plugin-Y.Z/</pre></div><p>Some developers have <a class="externalLink" href="http://www.nabble.com/site%3Astage-deploy-asks-for-a-password--tt15582961s177.html"> reported problems</a> with the <tt>site:stage-deploy</tt> goal. In that case, you can stage the site locally and upload it manually:</p><div class="source"><pre>mvn site site:stage -Preporting
+scp -r target/staging/people.apache.org/www/maven.apache.org/plugins/maven-XXX-plugin YOUR_APACHE_USERNAME@people.apache.org:/www/maven.apache.org/plugins/maven-XXX-plugin-Y.Z</pre></div></li><li>Verify/change folder permissions to 0775 and files permissions to 0664. Log on to <tt>people.apache.org</tt> and change to the directory above the staging directory. Then run these commands:<div class="source"><pre>cd /www/maven.apache.org/plugins
+find . -type d -exec chmod a+rx,g+w {} \;
+find . -type f -exec chmod 664 {} \;</pre></div></li></ol></div><div class="section"><h3>Deploying the release website<a name="Deploying_the_release_website"></a></h3><p>After the release has passed, the site needs to be uploaded.</p><p><b>Note:</b> Be sure to generate and deploy the site using the same version of the release. Typically, you need to check out the tag (or go to <tt>target/checkout</tt>)</p><div class="source"><pre>cd target/checkout
+mvn site-deploy -Preporting</pre></div><p><b>Note:</b> You can not just copy the documentation from the staging site above into the released documentation as the links are not identical. See the email thread <a class="externalLink" href="http://www.nabble.com/forum/ViewPost.jtp?post=24018250&framed=y">http://www.nabble.com/forum/ViewPost.jtp?post=24018250&framed=y</a></p><p>To review the site, wait for the files to arrive at</p><div class="source"><pre>http://maven.apache.org/plugins/maven-XXX-plugin/</pre></div><p>The wait is necessary to allow the site to be <a class="externalLink" href="http://www.apache.org/dev/project-site.html">rsync'ed into production</a>.</p></div><div class="section"><h3>Updating the Maven site<a name="Updating_the_Maven_site"></a></h3><p>Check out the maven site project from <tt>https://svn.apache.org/repos/asf/maven/site/trunk</tt> or pull the latest changes if already checked out.</p><p>Update the version number for the plugin on the <tt>
src/site/apt/plugins/index.apt</tt> page.</p><p>Commit your changes and then deploy the site.</p><div class="source"><pre>mvn clean site-deploy</pre></div></div></div>
+ </div>
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ <div id="footer">
+ <div class="xright">
+ © 2002-2012
+ The Apache Software Foundation
+
+ - <a href="http://maven.apache.org/privacy-policy.html">Privacy Policy</a>.
+ Apache Maven, Maven, Apache, the Apache feather logo, and the Apache Maven project logos are trademarks of The Apache Software Foundation.
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ </body>
+</html>