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 2013/04/27 09:29:25 UTC
svn commit: r860084 [14/39] - in /websites/staging/maven/trunk/content: ./
background/ developers/ developers/conventions/ developers/release/
developers/website/ docs/2.0.1/ docs/2.0.10/ docs/2.0.11/ docs/2.0.2/
docs/2.0.3/ docs/2.0.4/ docs/2.0.5/ doc...
Modified: websites/staging/maven/trunk/content/guides/development/guide-m2-development.html
==============================================================================
--- websites/staging/maven/trunk/content/guides/development/guide-m2-development.html (original)
+++ websites/staging/maven/trunk/content/guides/development/guide-m2-development.html Sat Apr 27 07:29:22 2013
@@ -1,6 +1,6 @@
<!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 Apr 23, 2013
+ | Generated by Apache Maven Doxia at Apr 27, 2013
| Rendered using Apache Maven Stylus Skin 1.5
-->
<html xmlns="http://www.w3.org/1999/xhtml">
@@ -16,7 +16,7 @@
Trygve Laugstol
Brett Porter" />
<meta name="Date-Creation-yyyymmdd" content="20080704" />
- <meta name="Date-Revision-yyyymmdd" content="20130423" />
+ <meta name="Date-Revision-yyyymmdd" content="20130427" />
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script>
@@ -46,7 +46,7 @@ Brett Porter" />
Guide to Developing Maven
</div>
<div class="xright">
- Last Published: 2013-04-23
+ Last Published: 2013-04-27
</div>
<div class="clear">
<hr/>
@@ -234,13 +234,108 @@ Brett Porter" />
</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. --><!-- NOTE: For help with the syntax of this file, see: --><!-- http://maven.apache.org/doxia/referen
ces/apt-format.html --><div class="section"><h2>Developing Maven<a name="Developing_Maven"></a></h2><p>This document describes how to get started into developing Maven itself. There is a separate page describing how to <a href="./guide-building-m2.html">building Maven</a>.</p><div class="section"><h3>Finding some work to do<a name="Finding_some_work_to_do"></a></h3><p>First of all you need something to work on! Unless you have found a particular issue you would like to work on the Maven team has categorized a few issues that we could use <i>your</i> help to solve them.</p><p>JIRA has RSS feeds available if you'd like to include those in your favorite feed aggregator.</p><p>We categorize the issues in three different categories:</p><ul><li><b><a class="externalLink" href="http://jira.codehaus.org/secure/IssueNavigator.jspa?pid=10500&resolutionIds=-1&customfield_10010=Novice&sorter/field=priority&sorter/order=ASC&sorter/field=issuekey&sorter/order=ASC&a
mp;tempMax=25&reset=true">Novice</a></b>: No previous exposure to the code needed. <i>(<a class="externalLink" href="http://jira.codehaus.org/secure/IssueNavigator.jspa?view=rss&pid=10500&resolutionIds=-1&customfield_10010=Novice&sorter/field=priority&sorter/order=ASC&sorter/field=issuekey&sorter/order=ASC&tempMax=25&reset=true&decorator=none">rss feed</a>)</i></li><li><b><a class="externalLink" href="http://jira.codehaus.org/secure/IssueNavigator.jspa?pid=10500&resolutionIds=-1&customfield_10010=Intermediate&sorter/field=priority&sorter/order=ASC&sorter/field=issuekey&sorter/order=ASC&tempMax=25&reset=true">Intermediate</a></b>: Exposure to Maven pluins and/or internals required. <i>(<a class="externalLink" href="http://jira.codehaus.org/secure/IssueNavigator.jspa?view=rss&pid=10500&resolutionIds=-1&customfield_10010=Intermediate&sorter/field=priority&sorter/order=ASC&sorter/
field=issuekey&sorter/order=ASC&tempMax=25&reset=true&decorator=none">rss feed</a>)</i></li><li><b><a class="externalLink" href="http://jira.codehaus.org/secure/IssueNavigator.jspa?pid=10500&resolutionIds=-1&customfield_10010=Expert&sorter/field=priority&sorter/order=ASC&sorter/field=issuekey&sorter/order=ASC&tempMax=25&reset=true">Expert</a></b>: Good knowledge of Maven internals and it's dependencies required. <i>(<a class="externalLink" href="http://jira.codehaus.org/secure/IssueNavigator.jspa?view=rss&pid=10500&resolutionIds=-1&customfield_10010=Expert&sorter/field=priority&sorter/order=ASC&sorter/field=issuekey&sorter/order=ASC&tempMax=25&reset=true&decorator=none">rss feed</a>)</i></li></ul><p>When you find a issue you would like to work on add a comment in the issue log so the core developers and other people looking for work know that someone is already working on it.</p></div><di
v class="section"><h3>Where's the source?<a name="Wheres_the_source"></a></h3><p>See <a href="/source-repository.html">http://maven.apache.prg/source-repository.html</a> for information. The Maven project uses a GIT for some things, and Subversion for others, and this page tracks the situation.</p></div><div class="section"><h3>Don't forget tests!<a name="Dont_forget_tests"></a></h3><p>You will find many unit tests in the maven-3 tree. If at all possible, create or modify a unit test to demonstrate the problem, and then validate your fix.</p><p>If the problem case can't be set up in the unit tests, add an integration test.</p><p>Before submitting a patch, in any case, you should run all of the integration tests. The tests require an empty local repository.</p><p>Ant version 1.8+ is recommended.</p><div class="source"><pre>cd maven
+ <!-- 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. --><!-- NOTE: For help with the syntax of this file, see: --><!-- http://maven.apache.org/doxia/referen
ces/apt-format.html --><div class="section">
+<h2>Developing Maven<a name="Developing_Maven"></a></h2>
+<p>This document describes how to get started into developing Maven itself. There is a separate page describing how to <a href="./guide-building-m2.html">building Maven</a>.</p>
+<div class="section">
+<h3>Finding some work to do<a name="Finding_some_work_to_do"></a></h3>
+<p>First of all you need something to work on! Unless you have found a particular issue you would like to work on the Maven team has categorized a few issues that we could use <i>your</i> help to solve them.</p>
+<p>JIRA has RSS feeds available if you'd like to include those in your favorite feed aggregator.</p>
+<p>We categorize the issues in three different categories:</p>
+<ul>
+<li><b><a class="externalLink" href="http://jira.codehaus.org/secure/IssueNavigator.jspa?pid=10500&resolutionIds=-1&customfield_10010=Novice&sorter/field=priority&sorter/order=ASC&sorter/field=issuekey&sorter/order=ASC&tempMax=25&reset=true">Novice</a></b>: No previous exposure to the code needed. <i>(<a class="externalLink" href="http://jira.codehaus.org/secure/IssueNavigator.jspa?view=rss&pid=10500&resolutionIds=-1&customfield_10010=Novice&sorter/field=priority&sorter/order=ASC&sorter/field=issuekey&sorter/order=ASC&tempMax=25&reset=true&decorator=none">rss feed</a>)</i></li>
+<li><b><a class="externalLink" href="http://jira.codehaus.org/secure/IssueNavigator.jspa?pid=10500&resolutionIds=-1&customfield_10010=Intermediate&sorter/field=priority&sorter/order=ASC&sorter/field=issuekey&sorter/order=ASC&tempMax=25&reset=true">Intermediate</a></b>: Exposure to Maven pluins and/or internals required. <i>(<a class="externalLink" href="http://jira.codehaus.org/secure/IssueNavigator.jspa?view=rss&pid=10500&resolutionIds=-1&customfield_10010=Intermediate&sorter/field=priority&sorter/order=ASC&sorter/field=issuekey&sorter/order=ASC&tempMax=25&reset=true&decorator=none">rss feed</a>)</i></li>
+<li><b><a class="externalLink" href="http://jira.codehaus.org/secure/IssueNavigator.jspa?pid=10500&resolutionIds=-1&customfield_10010=Expert&sorter/field=priority&sorter/order=ASC&sorter/field=issuekey&sorter/order=ASC&tempMax=25&reset=true">Expert</a></b>: Good knowledge of Maven internals and it's dependencies required. <i>(<a class="externalLink" href="http://jira.codehaus.org/secure/IssueNavigator.jspa?view=rss&pid=10500&resolutionIds=-1&customfield_10010=Expert&sorter/field=priority&sorter/order=ASC&sorter/field=issuekey&sorter/order=ASC&tempMax=25&reset=true&decorator=none">rss feed</a>)</i></li></ul>
+<p>When you find a issue you would like to work on add a comment in the issue log so the core developers and other people looking for work know that someone is already working on it.</p></div>
+<div class="section">
+<h3>Where's the source?<a name="Wheres_the_source"></a></h3>
+<p>See <a href="/source-repository.html">http://maven.apache.prg/source-repository.html</a> for information. The Maven project uses a GIT for some things, and Subversion for others, and this page tracks the situation.</p></div>
+<div class="section">
+<h3>Don't forget tests!<a name="Dont_forget_tests"></a></h3>
+<p>You will find many unit tests in the maven-3 tree. If at all possible, create or modify a unit test to demonstrate the problem, and then validate your fix.</p>
+<p>If the problem case can't be set up in the unit tests, add an integration test.</p>
+<p>Before submitting a patch, in any case, you should run all of the integration tests. The tests require an empty local repository.</p>
+<p>Ant version 1.8+ is recommended.</p>
+<div class="source">
+<pre>cd maven
export M2_HOME=/place-to-put-test-maven-root
ant all (or with -Dmaven.home=/place-to-put-test-maven-root )
cd ../maven-integration-testing
rm -rf /tmp/it.repo
-/place-to-put-test-maven-root/bin/mvn -Prun-its -B -U clean install -Dmaven.repo.local=/tmp/it.repo -Dmaven.home=/place-to-put-test-maven-root</pre></div><p>To run a single test, change the last command line to:</p><div class="source"><pre>cd ../maven-integration-testing/core-it-suite
-[whatever]/mvn -Dtest=yourit [other options]</pre></div></div><div class="section"><h3><a name="Creating_and_submitting_a_patch">Creating and submitting a patch</a></h3><p>When you have either completed an issue or just want some feedback on the work you have done, create a patch and attach the patch to the issue in question. We have a couple of guidelines when creating patches:</p><ul><li>Patch the trunk, not a tag. Otherwise, your patch is outdated the moment you create it and might not be applicable to the development head.</li><li>Always create the patch from the root of the Maven project, i.e. where the <tt>pom.xml</tt> file is.</li><li>If this was a new piece of work without a JIRA issue, create a JIRA issue for it now.</li><li>Name the file <tt>MNG-<issue number>-<artifact id>.patch</tt>.</li><li>Attach the patch to the JIRA issue you were working on (do not paste its content in as a comment though). When adding the patch add a comment to the issue explain
ing what it does. Shortly after, someone will apply the patch and close the issue.</li></ul><p>An example on how to create a patch from the command line:</p><div><pre>$ svn diff > MNG-123-maven-core.patch</pre></div><p>If you are picking up an issue with a existing patch attached to the issue you can apply the patch to your working directory directly from JIRA like this. The <tt>wget</tt> and <tt>patch</tt> commands will only be available if you are on a UNIX platform or using Cygwin on windows.</p><div><pre>$ wget -O - -q <URL to the patch from JIRA> | patch -p0</pre></div><p>If the patch is in a local file <tt>MNG-123.patch</tt> and you want to apply that use this command:</p><div><pre>$ patch -p0 < MNG-123.patch</pre></div><p>A couple of notes:</p><ul><li>If you are using another tool for creating patches, make sure that the patch doesn't include absolute paths. Including absolute paths in the patch will make the useless for us as we most likely don't have the
same directory structure as you.</li><li>Make sure that you follow our code style, see <a href="#Further_Links">Further Links</a>.</li></ul></div><div class="section"><h3>Patch acceptance criteria<a name="Patch_acceptance_criteria"></a></h3></div></div><div class="section"><h2>There are a number of criteria that a patch will be judged on:<a name="There_are_a_number_of_criteria_that_a_patch_will_be_judged_on:"></a></h2><ul><li>Whether it works and does what is intended. This one is probably obvious!</li><li>Whether it fits the spirit of the project. Some patches may be rejected as they take the project in a different direction to that which the current development community has chosen. This is usually discussed on an issue well before a patch is contributed, so if you are unsure, discuss it there or on the mailing lists first. Feel free to continue discussing it (with new justification) if you disagree, or appeal to a wider audience on the mailing lists.</li><li>Whether it c
ontains tests. It is expected that any patches relating to functionality will be accompanied by unit tests and/or integration tests. It is strongly desired (and will be requested) for bug fixes too, but will not be the basis for not applying it. At a bare minimum, the change should not decrease the amount of automated test coverage. As a community, we are focusing on increasing the current coverage, as there are several areas that do not receive automated testing.</li><li>Whether it contains documentation. All new functionality needs to be documented for users, even if it is very rough for someone to expand on later. While rough is acceptable, incomplete is not. As with automated testing, as a community we are striving to increase the current coverage of documentation.</li></ul></div><div class="section"><h2>Above all, don't be discouraged. These are the same requirements the current committers should hold each other to as well. And remember, your contributions are always we
lcome!<a name="Above_all_dont_be_discouraged._These_are_the_same_requirements_the_current_committers_should_hold_each_other_to_as_well._And_remember_your_contributions_are_always_welcome"></a></h2><div class="section"><h3>Related Projects<a name="Related_Projects"></a></h3><p>Maven has a few dependencies on other projects.</p><ul><li><b>Plexus</b><p>Plexus is a full-fledged container supporting different kinds of component lifecycles. It's native lifecycle is like any other modern IoC container, using field injection of both requirements and configuration. All core Maven functionality are Plexus components.</p><p>You can <a class="externalLink" href="http://plexus.codehaus.org">read more about Plexus</a>.</p></li><li><b>Modello</b><p>Modello is a simple tool for representing an object model and generate code and resources from the model. Maven is using Modello to generate all Java objects, XML readers and writers, XML Schema and HTML documentation.</p><p>You can <a class="ex
ternalLink" href="http://modello.codehaus.org">read more about Modello</a>.</p></li><li><b>Mojo</b><p>"Mojo" is really two things when it comes to Maven. It is both Maven's plug-in API but also a separate Codehaus project hosting these plugins.</p><p><a class="externalLink" href="http://mojo.codehaus.org">The Mojo Project</a> is a plugin forge for non-core Maven plugins. There is also a lower bar for becoming a part of the project.</p></li></ul></div><div class="section"><h3>Sub Projects<a name="Sub_Projects"></a></h3><ul><li>Maven Surefire<p>Surefire is a testing framework. It can run regular JUnit tests so you won't have to change anything in your code to use it. It support scripting tests in BeanShell and Jython and has special "batteries" for writing acceptance and functional tests for the web and for testing XML-RPC code.</p><p>You can <a class="externalLink" href="http://maven.apache.org/surefire/">read more about Surefire</a>.</p></li><li>Maven Dox
ia<p>Doxia is Maven's documentation engine. It has a sink and parser API that can be used to plug in support for input and output documents.</p><p>You can read more about <a class="externalLink" href="http://maven.apache.org/doxia/">Doxia</a> and the currently supported <a class="externalLink" href="http://maven.apache.org/doxia/references/index.html">document formats</a>.</p></li></ul><div class="section"><h4>Maven SCM<a name="Maven_SCM"></a></h4><p>Maven SCM (Source Control Management) is an reusable API which is independent of Maven itself and it is used by the SCM related Maven Plugins. The core part of Maven itself doesn't depend on Maven SCM.</p><p>You can <a class="externalLink" href="http://maven.apache.org/scm/">read more about Scm</a>.</p></div><div class="section"><h4>Maven Wagon<a name="Maven_Wagon"></a></h4><p>Maven Wagon is also a standalone API that deals with transporting files and directories. Maven Core uses the Wagon API to download and upload artifacts an
d artifact metadata and the site plug-in uses it to publish the site.</p><p>You can <a class="externalLink" href="http://maven.apache.org/wagon/">read more about Wagon</a>.</p></div></div><div class="section"><h3><a name="Further_Links">Further Links</a></h3><ul><li><a href="../../developers/conventions/code.html">Maven Code Style And Code Convention</a></li><li><a href="../../developers/conventions/jira.html">Maven JIRA Convention</a></li><li><a href="../../developers/conventions/svn.html">Maven SVN Convention</a></li></ul></div></div>
+/place-to-put-test-maven-root/bin/mvn -Prun-its -B -U clean install -Dmaven.repo.local=/tmp/it.repo -Dmaven.home=/place-to-put-test-maven-root</pre></div>
+<p>To run a single test, change the last command line to:</p>
+<div class="source">
+<pre>cd ../maven-integration-testing/core-it-suite
+[whatever]/mvn -Dtest=yourit [other options]</pre></div></div>
+<div class="section">
+<h3><a name="Creating_and_submitting_a_patch">Creating and submitting a patch</a></h3>
+<p>When you have either completed an issue or just want some feedback on the work you have done, create a patch and attach the patch to the issue in question. We have a couple of guidelines when creating patches:</p>
+<ul>
+<li>Patch the trunk, not a tag. Otherwise, your patch is outdated the moment you create it and might not be applicable to the development head.</li>
+<li>Always create the patch from the root of the Maven project, i.e. where the <tt>pom.xml</tt> file is.</li>
+<li>If this was a new piece of work without a JIRA issue, create a JIRA issue for it now.</li>
+<li>Name the file <tt>MNG-<issue number>-<artifact id>.patch</tt>.</li>
+<li>Attach the patch to the JIRA issue you were working on (do not paste its content in as a comment though). When adding the patch add a comment to the issue explaining what it does. Shortly after, someone will apply the patch and close the issue.</li></ul>
+<p>An example on how to create a patch from the command line:</p>
+<div>
+<pre>$ svn diff > MNG-123-maven-core.patch</pre></div>
+<p>If you are picking up an issue with a existing patch attached to the issue you can apply the patch to your working directory directly from JIRA like this. The <tt>wget</tt> and <tt>patch</tt> commands will only be available if you are on a UNIX platform or using Cygwin on windows.</p>
+<div>
+<pre>$ wget -O - -q <URL to the patch from JIRA> | patch -p0</pre></div>
+<p>If the patch is in a local file <tt>MNG-123.patch</tt> and you want to apply that use this command:</p>
+<div>
+<pre>$ patch -p0 < MNG-123.patch</pre></div>
+<p>A couple of notes:</p>
+<ul>
+<li>If you are using another tool for creating patches, make sure that the patch doesn't include absolute paths. Including absolute paths in the patch will make the useless for us as we most likely don't have the same directory structure as you.</li>
+<li>Make sure that you follow our code style, see <a href="#Further_Links">Further Links</a>.</li></ul></div>
+<div class="section">
+<h3>Patch acceptance criteria<a name="Patch_acceptance_criteria"></a></h3></div></div>
+<div class="section">
+<h2>There are a number of criteria that a patch will be judged on:<a name="There_are_a_number_of_criteria_that_a_patch_will_be_judged_on:"></a></h2>
+<ul>
+<li>Whether it works and does what is intended. This one is probably obvious!</li>
+<li>Whether it fits the spirit of the project. Some patches may be rejected as they take the project in a different direction to that which the current development community has chosen. This is usually discussed on an issue well before a patch is contributed, so if you are unsure, discuss it there or on the mailing lists first. Feel free to continue discussing it (with new justification) if you disagree, or appeal to a wider audience on the mailing lists.</li>
+<li>Whether it contains tests. It is expected that any patches relating to functionality will be accompanied by unit tests and/or integration tests. It is strongly desired (and will be requested) for bug fixes too, but will not be the basis for not applying it. At a bare minimum, the change should not decrease the amount of automated test coverage. As a community, we are focusing on increasing the current coverage, as there are several areas that do not receive automated testing.</li>
+<li>Whether it contains documentation. All new functionality needs to be documented for users, even if it is very rough for someone to expand on later. While rough is acceptable, incomplete is not. As with automated testing, as a community we are striving to increase the current coverage of documentation.</li></ul></div>
+<div class="section">
+<h2>Above all, don't be discouraged. These are the same requirements the current committers should hold each other to as well. And remember, your contributions are always welcome!<a name="Above_all_dont_be_discouraged._These_are_the_same_requirements_the_current_committers_should_hold_each_other_to_as_well._And_remember_your_contributions_are_always_welcome"></a></h2>
+<div class="section">
+<h3>Related Projects<a name="Related_Projects"></a></h3>
+<p>Maven has a few dependencies on other projects.</p>
+<ul>
+<li><b>Plexus</b>
+<p>Plexus is a full-fledged container supporting different kinds of component lifecycles. It's native lifecycle is like any other modern IoC container, using field injection of both requirements and configuration. All core Maven functionality are Plexus components.</p>
+<p>You can <a class="externalLink" href="http://plexus.codehaus.org">read more about Plexus</a>.</p></li>
+<li><b>Modello</b>
+<p>Modello is a simple tool for representing an object model and generate code and resources from the model. Maven is using Modello to generate all Java objects, XML readers and writers, XML Schema and HTML documentation.</p>
+<p>You can <a class="externalLink" href="http://modello.codehaus.org">read more about Modello</a>.</p></li>
+<li><b>Mojo</b>
+<p>"Mojo" is really two things when it comes to Maven. It is both Maven's plug-in API but also a separate Codehaus project hosting these plugins.</p>
+<p><a class="externalLink" href="http://mojo.codehaus.org">The Mojo Project</a> is a plugin forge for non-core Maven plugins. There is also a lower bar for becoming a part of the project.</p></li></ul></div>
+<div class="section">
+<h3>Sub Projects<a name="Sub_Projects"></a></h3>
+<ul>
+<li>Maven Surefire
+<p>Surefire is a testing framework. It can run regular JUnit tests so you won't have to change anything in your code to use it. It support scripting tests in BeanShell and Jython and has special "batteries" for writing acceptance and functional tests for the web and for testing XML-RPC code.</p>
+<p>You can <a class="externalLink" href="http://maven.apache.org/surefire/">read more about Surefire</a>.</p></li>
+<li>Maven Doxia
+<p>Doxia is Maven's documentation engine. It has a sink and parser API that can be used to plug in support for input and output documents.</p>
+<p>You can read more about <a class="externalLink" href="http://maven.apache.org/doxia/">Doxia</a> and the currently supported <a class="externalLink" href="http://maven.apache.org/doxia/references/index.html">document formats</a>.</p></li></ul>
+<div class="section">
+<h4>Maven SCM<a name="Maven_SCM"></a></h4>
+<p>Maven SCM (Source Control Management) is an reusable API which is independent of Maven itself and it is used by the SCM related Maven Plugins. The core part of Maven itself doesn't depend on Maven SCM.</p>
+<p>You can <a class="externalLink" href="http://maven.apache.org/scm/">read more about Scm</a>.</p></div>
+<div class="section">
+<h4>Maven Wagon<a name="Maven_Wagon"></a></h4>
+<p>Maven Wagon is also a standalone API that deals with transporting files and directories. Maven Core uses the Wagon API to download and upload artifacts and artifact metadata and the site plug-in uses it to publish the site.</p>
+<p>You can <a class="externalLink" href="http://maven.apache.org/wagon/">read more about Wagon</a>.</p></div></div>
+<div class="section">
+<h3><a name="Further_Links">Further Links</a></h3>
+<ul>
+<li><a href="../../developers/conventions/code.html">Maven Code Style And Code Convention</a></li>
+<li><a href="../../developers/conventions/jira.html">Maven JIRA Convention</a></li>
+<li><a href="../../developers/conventions/svn.html">Maven SVN Convention</a></li></ul></div></div>
</div>
</div>
<div class="clear">
Modified: websites/staging/maven/trunk/content/guides/development/guide-plugin-documentation.html
==============================================================================
--- websites/staging/maven/trunk/content/guides/development/guide-plugin-documentation.html (original)
+++ websites/staging/maven/trunk/content/guides/development/guide-plugin-documentation.html Sat Apr 27 07:29:22 2013
@@ -1,6 +1,6 @@
<!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 Apr 23, 2013
+ | Generated by Apache Maven Doxia at Apr 27, 2013
| Rendered using Apache Maven Stylus Skin 1.5
-->
<html xmlns="http://www.w3.org/1999/xhtml">
@@ -13,7 +13,7 @@
</style>
<link rel="stylesheet" href="../../css/print.css" type="text/css" media="print" />
<meta name="author" content="Maven Team" />
- <meta name="Date-Revision-yyyymmdd" content="20130423" />
+ <meta name="Date-Revision-yyyymmdd" content="20130427" />
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script>
@@ -43,7 +43,7 @@
Guide to the Plugin Documentation Standard
</div>
<div class="xright">
- Last Published: 2013-04-23
+ Last Published: 2013-04-27
</div>
<div class="clear">
<hr/>
@@ -231,12 +231,53 @@
</div>
<div id="bodyColumn">
<div id="contentBox">
- <div class="section"><h2>Introduction<a name="Introduction"></a></h2><div class="section"><h3>Where did the standard came from?<a name="Where_did_the_standard_came_from"></a></h3><p>The plugin documentation standard was created to address the frequent complain of lack of documentation, specifically on the Maven plugins. The standard was based on the suggestions made on the Maven dev mailing list with some refinements. It is a community consensus of what basic documentation a Maven plugin should have. </p></div><div class="section"><h3>Why do we need a documentation standard?<a name="Why_do_we_need_a_documentation_standard"></a></h3><p>The standard is not a set of rules but a guide to help plugin developers document their plugins better, for the benefit of the users of the plugin. The standard also reminds the plugin developers of the important details that needs to be documented, to help speed up the adoption of the plugin.</p></div></div><div class="section"><h2>Gen
erated Documentation <a name="Generated_Documentation"></a></h2><p>It is recommended that you let Maven generate the basic information for the plugin to make sure that that the basic information is always accurate and synchronized with the plugin implementation. </p><p>Documentation is generated by running </p><div class="source"><pre>mvn site</pre></div><p>It will generate a plugin site based on the information in the POM, <tt>src/site</tt> and other reporting plugins configured in the POM. The most important reporting plugin is the <a class="externalLink" href="http://maven.apache.org/plugins/maven-plugin-plugin/">Maven Plugin Plugin</a> which will generate the documentation for each plugin goal based on the mojo annotations. But in order for the generated site to be usable, the required information should be available to the Maven Site Plugin.</p><div class="section"><h3>POM Elements<a name="POM_Elements"></a></h3><p>Maven extracts the information from the POM to generate
the pages under Project Information. The first step in having a good documentation is to have an accurate and visible basic project information, Maven can provide this for the plugin as long as the information in the POM is complete, descriptive and accurate.</p><div class="section"><h4>Required Elements<a name="Required_Elements"></a></h4><p>Minimum elements for a valid POM:</p><ul><li><tt><modelVersion></tt> - POM model version, currently 4.0.0</li><li><tt><groupId></tt> - the package name</li><li><tt><artifactId></tt> - artifact name</li><li><tt><packaging></tt> - type of artifact produced by the POM</li><li><tt><version></tt> - the plugin version</li></ul></div><div class="section"><h4>Optional Elements <a name="Optional_Elements"></a></h4><p>These might be optional elements in a valid POM but they are important basic project information required by the users to effectively use the plugin:</p><ul><li><tt><name></tt> - plugin's name, <
i>Maven NNN Plugin</i> for plugins hosted at the Maven project or <i>NNN Maven Plugin</i> for all others</li><li><tt><description></tt> - project description, an overview of what the plugin can do</li><li><tt><url></tt> - the site of the plugin, normally <i>maven.apache.org</i> or <i>mojo.codehaus.org</i></li><li><tt><prerequisites></tt> - the minimum version of Maven required to use this plugin</li><li><tt><issueManagement></tt> - describes the system used for reporting problems and modification requests<div class="source"><pre> [...]
+ <div class="section">
+<h2>Introduction<a name="Introduction"></a></h2>
+<div class="section">
+<h3>Where did the standard came from?<a name="Where_did_the_standard_came_from"></a></h3>
+<p>The plugin documentation standard was created to address the frequent complain of lack of documentation, specifically on the Maven plugins. The standard was based on the suggestions made on the Maven dev mailing list with some refinements. It is a community consensus of what basic documentation a Maven plugin should have. </p></div>
+<div class="section">
+<h3>Why do we need a documentation standard?<a name="Why_do_we_need_a_documentation_standard"></a></h3>
+<p>The standard is not a set of rules but a guide to help plugin developers document their plugins better, for the benefit of the users of the plugin. The standard also reminds the plugin developers of the important details that needs to be documented, to help speed up the adoption of the plugin.</p></div></div>
+<div class="section">
+<h2>Generated Documentation <a name="Generated_Documentation"></a></h2>
+<p>It is recommended that you let Maven generate the basic information for the plugin to make sure that that the basic information is always accurate and synchronized with the plugin implementation. </p>
+<p>Documentation is generated by running </p>
+<div class="source">
+<pre>mvn site</pre></div>
+<p>It will generate a plugin site based on the information in the POM, <tt>src/site</tt> and other reporting plugins configured in the POM. The most important reporting plugin is the <a class="externalLink" href="http://maven.apache.org/plugins/maven-plugin-plugin/">Maven Plugin Plugin</a> which will generate the documentation for each plugin goal based on the mojo annotations. But in order for the generated site to be usable, the required information should be available to the Maven Site Plugin.</p>
+<div class="section">
+<h3>POM Elements<a name="POM_Elements"></a></h3>
+<p>Maven extracts the information from the POM to generate the pages under Project Information. The first step in having a good documentation is to have an accurate and visible basic project information, Maven can provide this for the plugin as long as the information in the POM is complete, descriptive and accurate.</p>
+<div class="section">
+<h4>Required Elements<a name="Required_Elements"></a></h4>
+<p>Minimum elements for a valid POM:</p>
+<ul>
+<li><tt><modelVersion></tt> - POM model version, currently 4.0.0</li>
+<li><tt><groupId></tt> - the package name</li>
+<li><tt><artifactId></tt> - artifact name</li>
+<li><tt><packaging></tt> - type of artifact produced by the POM</li>
+<li><tt><version></tt> - the plugin version</li></ul></div>
+<div class="section">
+<h4>Optional Elements <a name="Optional_Elements"></a></h4>
+<p>These might be optional elements in a valid POM but they are important basic project information required by the users to effectively use the plugin:</p>
+<ul>
+<li><tt><name></tt> - plugin's name, <i>Maven NNN Plugin</i> for plugins hosted at the Maven project or <i>NNN Maven Plugin</i> for all others</li>
+<li><tt><description></tt> - project description, an overview of what the plugin can do</li>
+<li><tt><url></tt> - the site of the plugin, normally <i>maven.apache.org</i> or <i>mojo.codehaus.org</i></li>
+<li><tt><prerequisites></tt> - the minimum version of Maven required to use this plugin</li>
+<li><tt><issueManagement></tt> - describes the system used for reporting problems and modification requests
+<div class="source">
+<pre> [...]
<issueManagement>
<system>jira</system>
<url>http://jira.someproject.org</url>
</issueManagement>
- [...] </pre></div></li><li><tt><inceptionYear></tt> - year the plugin was first created</li><li><tt><mailingLists></tt> - lists where other users or the developers can be contacted for help and discussions<div class="source"><pre> [...]
+ [...] </pre></div></li>
+<li><tt><inceptionYear></tt> - year the plugin was first created</li>
+<li><tt><mailingLists></tt> - lists where other users or the developers can be contacted for help and discussions
+<div class="source">
+<pre> [...]
<mailingLists>
<mailingList>
<name>Project users</name>
@@ -249,7 +290,10 @@
[...]
</mailingList>
</mailingLists>
- [...] </pre></div></li><li><tt><licenses></tt> - plugin license<div class="source"><pre> [...]
+ [...] </pre></div></li>
+<li><tt><licenses></tt> - plugin license
+<div class="source">
+<pre> [...]
<licenses>
<license>
<name>The Apache Software License, Version 2.0</name>
@@ -257,18 +301,29 @@
<distribution>repo</distribution>
</license>
</licenses>
- [...]</pre></div></li><li><tt><scm></tt> - the source code management configuration - a plugin without this would raise suspicion, might not be OSS<div class="source"><pre> [...]
+ [...]</pre></div></li>
+<li><tt><scm></tt> - the source code management configuration - a plugin without this would raise suspicion, might not be OSS
+<div class="source">
+<pre> [...]
<scm>
<connection>scm:svn:http://noonecares.com/some/plugin/project/trunk</connection>
<developerConnection>scm:svn:https://noonecares.com/some/plugin/project/trunk</developerConnection>
<url>http://noonecares.com/viewvc/some/project/trunk/</url>
</scm>
- [...]</pre></div></li><li><tt><organization></tt> - the organization maintaining the plugin, just in case we need someone to blame<div class="source"><pre> [...]
+ [...]</pre></div></li>
+<li><tt><organization></tt> - the organization maintaining the plugin, just in case we need someone to blame
+<div class="source">
+<pre> [...]
<organization>
<name>Noone Care Software Foundation</name>
<url>http://noonecare.org/</url>
</organization>
- [...]</pre></div></li></ul></div></div><div class="section"><h3>Plugin Configuration Parameters<a name="Plugin_Configuration_Parameters"></a></h3><p>The Maven Plugin Plugin is responsible for generating the Plugin Info site and needs to be added to the <tt><reporting></tt> section unless it is already inherited from a parent POM:</p><div class="source"><pre> [...]
+ [...]</pre></div></li></ul></div></div>
+<div class="section">
+<h3>Plugin Configuration Parameters<a name="Plugin_Configuration_Parameters"></a></h3>
+<p>The Maven Plugin Plugin is responsible for generating the Plugin Info site and needs to be added to the <tt><reporting></tt> section unless it is already inherited from a parent POM:</p>
+<div class="source">
+<pre> [...]
<reporting>
<plugins>
<plugin>
@@ -278,14 +333,22 @@
</plugin>
</plugins>
</reporting>
- [...] </pre></div><p>The comments, annotations and plugin parameter names are extracted from the plugin source and rendered in the Plugin Info page. In order for the generated site to be useful here are some guidelines you can follow when documenting your plugin.</p><ul><li>all <tt>@parameter</tt> fields should have a descriptive comment, informative enough that even a regular user can understand<div class="source"><pre> [...]
+ [...] </pre></div>
+<p>The comments, annotations and plugin parameter names are extracted from the plugin source and rendered in the Plugin Info page. In order for the generated site to be useful here are some guidelines you can follow when documenting your plugin.</p>
+<ul>
+<li>all <tt>@parameter</tt> fields should have a descriptive comment, informative enough that even a regular user can understand
+<div class="source">
+<pre> [...]
/**
* Put something informative here that a regular user can understand.
*
* @parameter
*/
private boolean someparameter;
- [...]</pre></div></li><li>class level comment should explain what the goal does<div class="source"><pre>[...]
+ [...]</pre></div></li>
+<li>class level comment should explain what the goal does
+<div class="source">
+<pre>[...]
/**
* Everything here will show up on the top of the generated plugin info page.
*
@@ -298,7 +361,16 @@ public class ExampleMojo
public void execute()
throws MojoExecutionException, MojoFailureException
{
-[...]</pre></div></li><li>the <tt>@component</tt> and <tt>@readonly</tt> parameters are not required to have any comments but it's still a good practice to provide one</li></ul></div><div class="section"><h3>Site Organization <a name="Site_Organization"></a></h3><p>Visibility of the information is also crucial, having uniform navigation links will greatly improve the visibility of the documentations. The index page can also help emphasize important sections and pages of the plugin documentation. </p><div class="section"><h4>Site Descriptor <a name="Site_Descriptor"></a></h4><p>The site descriptor describes the navigation links and can be found in <tt>src/site/site.xml</tt>. Below is the suggested site descriptor template.</p><div class="source"><pre><?xml version="1.0" encoding="UTF-8"?>
+[...]</pre></div></li>
+<li>the <tt>@component</tt> and <tt>@readonly</tt> parameters are not required to have any comments but it's still a good practice to provide one</li></ul></div>
+<div class="section">
+<h3>Site Organization <a name="Site_Organization"></a></h3>
+<p>Visibility of the information is also crucial, having uniform navigation links will greatly improve the visibility of the documentations. The index page can also help emphasize important sections and pages of the plugin documentation. </p>
+<div class="section">
+<h4>Site Descriptor <a name="Site_Descriptor"></a></h4>
+<p>The site descriptor describes the navigation links and can be found in <tt>src/site/site.xml</tt>. Below is the suggested site descriptor template.</p>
+<div class="source">
+<pre><?xml version="1.0" encoding="UTF-8"?>
<project>
<body>
<menu name="Overview">
@@ -313,7 +385,14 @@ public class ExampleMojo
<item name="description2" href="examples/example-two.html"/>
</menu>
</body>
-</project></pre></div><div class="section"><h5>Navigation Links<a name="Navigation_Links"></a></h5><ul><li>Introduction<p>The introduction is the front page of the plugin documentation. This is a good place to place any section and pages that needs to be emphasized. It is also suggested that the generated plugin parameter configuration be linked here. Below is the suggested <tt>src/site/apt/index.apt</tt> template</p><div class="source"><pre> ------
+</project></pre></div>
+<div class="section">
+<h5>Navigation Links<a name="Navigation_Links"></a></h5>
+<ul>
+<li>Introduction
+<p>The introduction is the front page of the plugin documentation. This is a good place to place any section and pages that needs to be emphasized. It is also suggested that the generated plugin parameter configuration be linked here. Below is the suggested <tt>src/site/apt/index.apt</tt> template</p>
+<div class="source">
+<pre> ------
Introduction
------
Author
@@ -360,7 +439,15 @@ Plugin Name
* {{{examples/example-one.html}Example Description One}}
* {{{examples/example-two.html}Example Description Two}}
- </pre></div></li><li>Goals<p><tt>plugin-info.html</tt> is generated by the Maven Plugin Plugin. Until the Maven Site Plugin is updated it would be better to pull it out to the main menu for greater visibility. This contains the goals and their descriptions with a link to the configuration parameters. The information is based on the comments and annotations of the plugin. </p></li><li>Usage (this was previously called Howto)<p>The usage page describes the the basic use cases for the plugin goals which includes sample POM configurations and explanation of how the goals work. </p></li><li>FAQ<p>A well documented project always collates frequently asked questions which are usually located in <tt>src/site/fml/faq.fml</tt>. The example below provides a template for your FAQ:</p><div class="source"><pre><?xml version="1.0" encoding="UTF-8"?>
+ </pre></div></li>
+<li>Goals
+<p><tt>plugin-info.html</tt> is generated by the Maven Plugin Plugin. Until the Maven Site Plugin is updated it would be better to pull it out to the main menu for greater visibility. This contains the goals and their descriptions with a link to the configuration parameters. The information is based on the comments and annotations of the plugin. </p></li>
+<li>Usage (this was previously called Howto)
+<p>The usage page describes the the basic use cases for the plugin goals which includes sample POM configurations and explanation of how the goals work. </p></li>
+<li>FAQ
+<p>A well documented project always collates frequently asked questions which are usually located in <tt>src/site/fml/faq.fml</tt>. The example below provides a template for your FAQ:</p>
+<div class="source">
+<pre><?xml version="1.0" encoding="UTF-8"?>
<faqs id="FAQ" title="Frequently Asked Questions">
<part id="General">
<faq id="question">
@@ -372,7 +459,22 @@ Plugin Name
</answer>
</faq>
</part>
-</faqs></pre></div></li><li>Examples<p>The advanced configurations and examples not covered in the usage page is located here. Advanced users who wants to maximize the use of a plugin can check the items here. Tips on how to use the plugin effectively is also a good thing to put here.</p><p>For examples of items under "Examples" check these plugin sites:</p><ul><li><a class="externalLink" href="http://maven.apache.org/plugins/maven-javadoc-plugin/">Maven Javadoc Plugin Examples</a></li><li><a class="externalLink" href="http://maven.apache.org/plugins/maven-war-plugin/">Maven War Plugin Examples</a></li></ul></li></ul></div></div></div><div class="section"><h3>Recommended Configured Reports<a name="Recommended_Configured_Reports"></a></h3><p>There are 2 recommended report plugins to enhance the plugin documentation, Javadoc and JXR.</p><ul><li>Maven Javadoc Plugin<p>Javadocs provide documentation that makes it easier for developers to know how to use a particu
lar class. Instead of reading and understanding the actual source code, the developer can use the Javadocs instead to lookup the class attributes and methods.</p><p>To enable javadoc for your plugin add the following to your <tt>pom.xml</tt></p><div class="source"><pre> [...]
+</faqs></pre></div></li>
+<li>Examples
+<p>The advanced configurations and examples not covered in the usage page is located here. Advanced users who wants to maximize the use of a plugin can check the items here. Tips on how to use the plugin effectively is also a good thing to put here.</p>
+<p>For examples of items under "Examples" check these plugin sites:</p>
+<ul>
+<li><a class="externalLink" href="http://maven.apache.org/plugins/maven-javadoc-plugin/">Maven Javadoc Plugin Examples</a></li>
+<li><a class="externalLink" href="http://maven.apache.org/plugins/maven-war-plugin/">Maven War Plugin Examples</a></li></ul></li></ul></div></div></div>
+<div class="section">
+<h3>Recommended Configured Reports<a name="Recommended_Configured_Reports"></a></h3>
+<p>There are 2 recommended report plugins to enhance the plugin documentation, Javadoc and JXR.</p>
+<ul>
+<li>Maven Javadoc Plugin
+<p>Javadocs provide documentation that makes it easier for developers to know how to use a particular class. Instead of reading and understanding the actual source code, the developer can use the Javadocs instead to lookup the class attributes and methods.</p>
+<p>To enable javadoc for your plugin add the following to your <tt>pom.xml</tt></p>
+<div class="source">
+<pre> [...]
<build>
[...]
</build>
@@ -391,7 +493,13 @@ Plugin Name
</plugins>
[...]
</reporting>
- [...]</pre></div><p>Check the documentation about the plugin's <a class="externalLink" href="http://maven.apache.org/plugins/maven-javadoc-plugin/javadoc-mojo.html"><tt>javadoc:javadoc</tt></a> goal for the advanced configurations.</p></li><li>Maven JXR Plugin<p>The Maven JXR Plugin generates a cross-reference of the project sources. The generated cross-references are also linked to the corresponding javadoc if javadoc is generated. The cross-references is great for those who wants to better understand the inner workings of the plugin.</p><p>To enable source code cross-references add the following to your <tt>pom.xml</tt></p><div class="source"><pre> [...]
+ [...]</pre></div>
+<p>Check the documentation about the plugin's <a class="externalLink" href="http://maven.apache.org/plugins/maven-javadoc-plugin/javadoc-mojo.html"><tt>javadoc:javadoc</tt></a> goal for the advanced configurations.</p></li>
+<li>Maven JXR Plugin
+<p>The Maven JXR Plugin generates a cross-reference of the project sources. The generated cross-references are also linked to the corresponding javadoc if javadoc is generated. The cross-references is great for those who wants to better understand the inner workings of the plugin.</p>
+<p>To enable source code cross-references add the following to your <tt>pom.xml</tt></p>
+<div class="source">
+<pre> [...]
<build>
[...]
</build>
@@ -404,7 +512,8 @@ Plugin Name
</plugin>
</plugins>
</reporting>
- [...] </pre></div><p>Check the <a class="externalLink" href="http://maven.apache.org/plugins/maven-jxr-plugin/jxr-mojo.html">JXR configuration page</a> for the possible configuration parameters.</p></li></ul></div></div>
+ [...] </pre></div>
+<p>Check the <a class="externalLink" href="http://maven.apache.org/plugins/maven-jxr-plugin/jxr-mojo.html">JXR configuration page</a> for the possible configuration parameters.</p></li></ul></div></div>
</div>
</div>
<div class="clear">
Modified: websites/staging/maven/trunk/content/guides/development/guide-testing-development-plugins.html
==============================================================================
--- websites/staging/maven/trunk/content/guides/development/guide-testing-development-plugins.html (original)
+++ websites/staging/maven/trunk/content/guides/development/guide-testing-development-plugins.html Sat Apr 27 07:29:22 2013
@@ -1,6 +1,6 @@
<!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 Apr 23, 2013
+ | Generated by Apache Maven Doxia at Apr 27, 2013
| Rendered using Apache Maven Stylus Skin 1.5
-->
<html xmlns="http://www.w3.org/1999/xhtml">
@@ -14,7 +14,7 @@
<link rel="stylesheet" href="../../css/print.css" type="text/css" media="print" />
<meta name="author" content="Brett Porter" />
<meta name="Date-Creation-yyyymmdd" content="20090802" />
- <meta name="Date-Revision-yyyymmdd" content="20130423" />
+ <meta name="Date-Revision-yyyymmdd" content="20130427" />
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script>
@@ -44,7 +44,7 @@
Guide to Testing Development Versions of Plugins
</div>
<div class="xright">
- Last Published: 2013-04-23
+ Last Published: 2013-04-27
</div>
<div class="clear">
<hr/>
@@ -232,7 +232,21 @@
</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. --><!-- NOTE: For help with the syntax of this file, see: --><!-- http://maven.apache.org/doxia/referen
ces/apt-format.html --><div class="section"><h2>Guide to Testing Development Versions of Plugins<a name="Guide_to_Testing_Development_Versions_of_Plugins"></a></h2><div class="section"><h3>Why would I want to do this?<a name="Why_would_I_want_to_do_this"></a></h3><p>If a bug you are encountering has been reported as fixed but not yet released, you can confirm that it has been fixed for you. Or perhaps you just like to live on the bleeding edge.</p><p>You are highly encouraged to join the development list for the project and provide your feedback, or help promote release of the plugin in question.</p><p><i>Note:</i> This is <b>not</b> recommended as an everyday or in production practice! Snapshots are for testing purposes only and are not official releases. For more information, see <a class="externalLink" href="http://www.apache.org/dev/release.html#what"> the Releases FAQ</a>.</p></div><div class="section"><h3>How do I do this?<a name="How_do_I_do_this"></a></h3><p>Developm
ent versions of Maven plugins are periodically published to the repository: <a class="externalLink" href="http://repository.apache.org/snapshots/">http://repository.apache.org/snapshots/</a>.</p><p><i>Note:</i> Currently, this is not done automatically by our continuous integration setup. This is coming soon.</p><p>Other sites may publish there own - for example, the Mojo project hosts theirs at <a class="externalLink" href="http://snapshots.repository.codehaus.org/">http://snapshots.repository.codehaus.org/</a></p><p>The first step is to include this in your project:</p><div><pre><project>
+ <!-- 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. --><!-- NOTE: For help with the syntax of this file, see: --><!-- http://maven.apache.org/doxia/referen
ces/apt-format.html --><div class="section">
+<h2>Guide to Testing Development Versions of Plugins<a name="Guide_to_Testing_Development_Versions_of_Plugins"></a></h2>
+<div class="section">
+<h3>Why would I want to do this?<a name="Why_would_I_want_to_do_this"></a></h3>
+<p>If a bug you are encountering has been reported as fixed but not yet released, you can confirm that it has been fixed for you. Or perhaps you just like to live on the bleeding edge.</p>
+<p>You are highly encouraged to join the development list for the project and provide your feedback, or help promote release of the plugin in question.</p>
+<p><i>Note:</i> This is <b>not</b> recommended as an everyday or in production practice! Snapshots are for testing purposes only and are not official releases. For more information, see <a class="externalLink" href="http://www.apache.org/dev/release.html#what"> the Releases FAQ</a>.</p></div>
+<div class="section">
+<h3>How do I do this?<a name="How_do_I_do_this"></a></h3>
+<p>Development versions of Maven plugins are periodically published to the repository: <a class="externalLink" href="http://repository.apache.org/snapshots/">http://repository.apache.org/snapshots/</a>.</p>
+<p><i>Note:</i> Currently, this is not done automatically by our continuous integration setup. This is coming soon.</p>
+<p>Other sites may publish there own - for example, the Mojo project hosts theirs at <a class="externalLink" href="http://snapshots.repository.codehaus.org/">http://snapshots.repository.codehaus.org/</a></p>
+<p>The first step is to include this in your project:</p>
+<div>
+<pre><project>
...
<pluginRepositories>
<pluginRepository>
@@ -241,7 +255,14 @@
</pluginRepository>
</pluginRepositories>
...
-</project></pre></div><p>After this is included, there are three ways to use the updated versions:</p><ul><li>Set the appropriate version in the plugin, eg <tt>2.0.1-SNAPSHOT</tt></li><li>If you have not specified a version, use the <tt>-U</tt> switch to update plugins for the given Maven run</li><li>You can have Maven automatically check for updates on a given interval, for example:<div><pre><project>
+</project></pre></div>
+<p>After this is included, there are three ways to use the updated versions:</p>
+<ul>
+<li>Set the appropriate version in the plugin, eg <tt>2.0.1-SNAPSHOT</tt></li>
+<li>If you have not specified a version, use the <tt>-U</tt> switch to update plugins for the given Maven run</li>
+<li>You can have Maven automatically check for updates on a given interval, for example:
+<div>
+<pre><project>
...
<pluginRepositories>
<pluginRepository>
@@ -258,7 +279,15 @@
</pluginRepository>
</pluginRepositories>
...
-</project></pre></div></li></ul><p><i>Note:</i> These last two techniques mean that <i>every</i> plugin will be updated to the latest snapshot version.</p><p>The development version will stop being used if the <tt><pluginRepository></tt> element is removed from your POM and the version is set back to the release version. If you are using the command line or an unspecified version, you will also need to remove the version from the local repository.</p></div><div class="section"><h3>Using Settings without Modifying the Project<a name="Using_Settings_without_Modifying_the_Project"></a></h3><p>If you are using the goals from the command line on a number of projects, you should include this in your <tt>settings.xml</tt> file instead.</p><p>You need to modify your <tt>~/.m2/settings.xml</tt> file to include two new profiles and then when you need access to the plugin snapshots use <tt>-Papache</tt>. The profile only needs to be enabled once so that the plugins can be d
ownloaded into you local repository. Once in your local repository Maven can succesfully resolve the dependencies and the profile no longer needs to be activated.</p><div class="source"><pre><settings>
+</project></pre></div></li></ul>
+<p><i>Note:</i> These last two techniques mean that <i>every</i> plugin will be updated to the latest snapshot version.</p>
+<p>The development version will stop being used if the <tt><pluginRepository></tt> element is removed from your POM and the version is set back to the release version. If you are using the command line or an unspecified version, you will also need to remove the version from the local repository.</p></div>
+<div class="section">
+<h3>Using Settings without Modifying the Project<a name="Using_Settings_without_Modifying_the_Project"></a></h3>
+<p>If you are using the goals from the command line on a number of projects, you should include this in your <tt>settings.xml</tt> file instead.</p>
+<p>You need to modify your <tt>~/.m2/settings.xml</tt> file to include two new profiles and then when you need access to the plugin snapshots use <tt>-Papache</tt>. The profile only needs to be enabled once so that the plugins can be downloaded into you local repository. Once in your local repository Maven can succesfully resolve the dependencies and the profile no longer needs to be activated.</p>
+<div class="source">
+<pre><settings>
...
<profiles>
<profile>
@@ -279,7 +308,16 @@
</profile>
</profiles>
...
-</settings></pre></div><p>When invoking Maven for Apache profile, do it like this:</p><div class="source"><pre>mvn -Papache <phase|goal></pre></div></div><div class="section"><h3>Using a Repository Manager<a name="Using_a_Repository_Manager"></a></h3><p>In addition to the above you may want to use a repository manager so that you can retain the builds you have been using. For information on this technique, see the <a href="./guide-testing-releases.html"> Guide to Testing Staged Releases</a>.</p></div><div class="section"><h3>How do I make changes to the source and test development versions of the plugins?<a name="How_do_I_make_changes_to_the_source_and_test_development_versions_of_the_plugins"></a></h3><p>For information on this, see the <a href="./guide-m2-development.html">Guide to Maven 2.0 Development</a>.</p></div></div>
+</settings></pre></div>
+<p>When invoking Maven for Apache profile, do it like this:</p>
+<div class="source">
+<pre>mvn -Papache <phase|goal></pre></div></div>
+<div class="section">
+<h3>Using a Repository Manager<a name="Using_a_Repository_Manager"></a></h3>
+<p>In addition to the above you may want to use a repository manager so that you can retain the builds you have been using. For information on this technique, see the <a href="./guide-testing-releases.html"> Guide to Testing Staged Releases</a>.</p></div>
+<div class="section">
+<h3>How do I make changes to the source and test development versions of the plugins?<a name="How_do_I_make_changes_to_the_source_and_test_development_versions_of_the_plugins"></a></h3>
+<p>For information on this, see the <a href="./guide-m2-development.html">Guide to Maven 2.0 Development</a>.</p></div></div>
</div>
</div>
<div class="clear">
Modified: websites/staging/maven/trunk/content/guides/development/guide-testing-releases.html
==============================================================================
--- websites/staging/maven/trunk/content/guides/development/guide-testing-releases.html (original)
+++ websites/staging/maven/trunk/content/guides/development/guide-testing-releases.html Sat Apr 27 07:29:22 2013
@@ -1,6 +1,6 @@
<!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 Apr 23, 2013
+ | Generated by Apache Maven Doxia at Apr 27, 2013
| Rendered using Apache Maven Stylus Skin 1.5
-->
<html xmlns="http://www.w3.org/1999/xhtml">
@@ -13,7 +13,7 @@
</style>
<link rel="stylesheet" href="../../css/print.css" type="text/css" media="print" />
<meta name="author" content="Maven Team" />
- <meta name="Date-Revision-yyyymmdd" content="20130423" />
+ <meta name="Date-Revision-yyyymmdd" content="20130427" />
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script>
@@ -43,7 +43,7 @@
Guide to Testing Staged Releases
</div>
<div class="xright">
- Last Published: 2013-04-23
+ Last Published: 2013-04-27
</div>
<div class="clear">
<hr/>
@@ -231,20 +231,65 @@
</div>
<div id="bodyColumn">
<div id="contentBox">
- <div class="section"><h2>Guide to Testing Staged Releases<a name="Guide_to_Testing_Staged_Releases"></a></h2><p>As part of the release process, the artifacts are staged in a temporary repository for testing and evaluation before voting. Such repositories are not available by default, so to use them your project must be configured appropriately.</p><p>The steps are as follows:</p><ul><li>add the repository or plugin repository to your POM or settings (see below)</li><li>ensure you are using the version being released of the artifacts in your project, e.g. by setting the <tt><version></tt> in the <tt><plugin></tt> tag.</li><li>test the release</li><li>remove the repository from your POM if it was specified there</li><li>remove the artifacts from your local repository when you have completed testing</li></ul><p>The repository configuration for testing a plugin will typically look something like this (it will be provided in the vote email):</p><div><pre> ...
+ <div class="section">
+<h2>Guide to Testing Staged Releases<a name="Guide_to_Testing_Staged_Releases"></a></h2>
+<p>As part of the release process, the artifacts are staged in a temporary repository for testing and evaluation before voting. Such repositories are not available by default, so to use them your project must be configured appropriately.</p>
+<p>The steps are as follows:</p>
+<ul>
+<li>add the repository or plugin repository to your POM or settings (see below)</li>
+<li>ensure you are using the version being released of the artifacts in your project, e.g. by setting the <tt><version></tt> in the <tt><plugin></tt> tag.</li>
+<li>test the release</li>
+<li>remove the repository from your POM if it was specified there</li>
+<li>remove the artifacts from your local repository when you have completed testing</li></ul>
+<p>The repository configuration for testing a plugin will typically look something like this (it will be provided in the vote email):</p>
+<div>
+<pre> ...
<pluginRepositories>
<pluginRepository>
<id>staged-releases</id>
<url>http://people.apache.org/~dfabulich/stage-repo</url>
</pluginRepository>
</pluginRepositories>
- ...</pre></div><p>The important thing is that the staged release does not pollute your eventual environment as it may change if the vote fails and the release is made again. This is why clearing the local repository is necessary, but if you are using a repository manager this is also important to clear. The following provides instructions for setting Archiva up in such a way that the artifacts are isolated already.</p><div class="section"><h3>Setting up Archiva to Test Staged Releases<a name="Setting_up_Archiva_to_Test_Staged_Releases"></a></h3><p>These steps will be similar for any repository manager - please refer to their individual documentation for instructions on how to configure remote proxies.</p><p>For Archiva, the first step is to create a new managed repository for the staged releases. This will ensure they remain isolated from your environment. On the repositories tab, add a new managed repository with the settings:</p><ul><li>Identifier = <tt>staged-releases</
tt></li><li>Name = Staged Releases</li><li>Directory = <tt>/path/to/repositories/staged-releases</tt></li><li>Uncheck 'Scannable'</li></ul><p>Next add a remote repository with settings similar to the following:</p><ul><li>Identifier = <tt>dfabulich.staged.releases</tt></li><li>Name = dfabulich Staged Releases</li><li>URL = <tt>http://people.apache.org/~dfabulich/staging-repo/</tt></li></ul><p>Finally, add a proxy connector to connect the two repositories:</p><ul><li>Managed repository = <tt>staged-releases</tt></li><li>Remote repository = <tt>dfabulich.staged</tt></li><li>Release policy = <tt>once</tt></li><li>Snapshot policy = <tt>never</tt></li><li>White list = <tt>org/apache/maven/**</tt></li></ul><p>You can then utilise this repository from your POM or settings in the same way, but with the alternate URL of <tt>http://localhost:8080/archiva/repository/staged-releases/</tt>.</p><p>The advantage of this approach is that you can usually remove your entire local repository a
fterwards and after removing the staged repository from your POM the artifacts will no longer be used. There is no need to remove the repository or artifacts from Archiva itself - unless a staged release is updated for further testing.</p><p>It is also quite easy to test another staged release at a later date by reusing the repository, or adding a proxy connector and remote repository for a different staging repository.</p><p>If you are using the repository mirroring technique to lock down to the repository manager in your environment, you would add an additional mirror to correspond to the additional repository in the POM, such as:</p><div><pre> ...
+ ...</pre></div>
+<p>The important thing is that the staged release does not pollute your eventual environment as it may change if the vote fails and the release is made again. This is why clearing the local repository is necessary, but if you are using a repository manager this is also important to clear. The following provides instructions for setting Archiva up in such a way that the artifacts are isolated already.</p>
+<div class="section">
+<h3>Setting up Archiva to Test Staged Releases<a name="Setting_up_Archiva_to_Test_Staged_Releases"></a></h3>
+<p>These steps will be similar for any repository manager - please refer to their individual documentation for instructions on how to configure remote proxies.</p>
+<p>For Archiva, the first step is to create a new managed repository for the staged releases. This will ensure they remain isolated from your environment. On the repositories tab, add a new managed repository with the settings:</p>
+<ul>
+<li>Identifier = <tt>staged-releases</tt></li>
+<li>Name = Staged Releases</li>
+<li>Directory = <tt>/path/to/repositories/staged-releases</tt></li>
+<li>Uncheck 'Scannable'</li></ul>
+<p>Next add a remote repository with settings similar to the following:</p>
+<ul>
+<li>Identifier = <tt>dfabulich.staged.releases</tt></li>
+<li>Name = dfabulich Staged Releases</li>
+<li>URL = <tt>http://people.apache.org/~dfabulich/staging-repo/</tt></li></ul>
+<p>Finally, add a proxy connector to connect the two repositories:</p>
+<ul>
+<li>Managed repository = <tt>staged-releases</tt></li>
+<li>Remote repository = <tt>dfabulich.staged</tt></li>
+<li>Release policy = <tt>once</tt></li>
+<li>Snapshot policy = <tt>never</tt></li>
+<li>White list = <tt>org/apache/maven/**</tt></li></ul>
+<p>You can then utilise this repository from your POM or settings in the same way, but with the alternate URL of <tt>http://localhost:8080/archiva/repository/staged-releases/</tt>.</p>
+<p>The advantage of this approach is that you can usually remove your entire local repository afterwards and after removing the staged repository from your POM the artifacts will no longer be used. There is no need to remove the repository or artifacts from Archiva itself - unless a staged release is updated for further testing.</p>
+<p>It is also quite easy to test another staged release at a later date by reusing the repository, or adding a proxy connector and remote repository for a different staging repository.</p>
+<p>If you are using the repository mirroring technique to lock down to the repository manager in your environment, you would add an additional mirror to correspond to the additional repository in the POM, such as:</p>
+<div>
+<pre> ...
<mirror>
<id>staged-releases-mirror</id>
<url>http://localhost:8080/archiva/repository/staged-releases/</url>
<mirrorOf>staged-releases</mirrorOf>
</mirror>
- ...</pre></div></div><div class="section"><h3>Using a Settings Profile<a name="Using_a_Settings_Profile"></a></h3><p>If you regularly test staged releases and want to have a more convenient way to add the repository to a build without modifying your POM, you may add a profile to your POM:</p><div><pre> ...
+ ...</pre></div></div>
+<div class="section">
+<h3>Using a Settings Profile<a name="Using_a_Settings_Profile"></a></h3>
+<p>If you regularly test staged releases and want to have a more convenient way to add the repository to a build without modifying your POM, you may add a profile to your POM:</p>
+<div>
+<pre> ...
<profiles>
<profile>
<id>staged-releases</id>
@@ -255,7 +300,11 @@
</pluginRepository>
</pluginRepositories>
</profile>
- ...</pre></div><p>With this in place, you can activate it by simply changing the plugin version to the one you are testing in the POM as above, then run the build with the following command:</p><div><pre>mvn clean install -Pstaged-releases</pre></div><p>Note that the same conditions apply as above about cleaning out the local repository to prevent pollution of your local build environment.</p></div></div>
+ ...</pre></div>
+<p>With this in place, you can activate it by simply changing the plugin version to the one you are testing in the POM as above, then run the build with the following command:</p>
+<div>
+<pre>mvn clean install -Pstaged-releases</pre></div>
+<p>Note that the same conditions apply as above about cleaning out the local repository to prevent pollution of your local build environment.</p></div></div>
</div>
</div>
<div class="clear">