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/01/02 01:40:47 UTC
svn commit: r844564 - in /websites/staging/maven/trunk/content: ./
guides/development/guide-m2-development.html maven-site-1.0-site.jar
Author: buildbot
Date: Wed Jan 2 00:40:47 2013
New Revision: 844564
Log:
Staging update by buildbot for maven
Modified:
websites/staging/maven/trunk/content/ (props changed)
websites/staging/maven/trunk/content/guides/development/guide-m2-development.html
websites/staging/maven/trunk/content/maven-site-1.0-site.jar
Propchange: websites/staging/maven/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Wed Jan 2 00:40:47 2013
@@ -1 +1 @@
-1427596
+1427605
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 Wed Jan 2 00:40:47 2013
@@ -231,13 +231,13 @@ 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>You'll need to clone two git repositories:</p><ul><li><a class="externalLink" href="https://git-wip-us.apache.org/repos/asf/maven.git">https://git-wip-us.apache.org/repos/asf/maven.git</a> The canonical repository for <a href="/ref/current">the core of Maven</a>.</li><li><a class="externalLink" href="https://git-wip-us.apache.org/repos/asf/maven-integration-testing.git">https://git-wip-us.apache.org/repos/asf/maven-integration-testing.git</a> The corresponding <a href="/core-its">integration test set</a>.</li></ul></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&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
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>Surefire</b><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><b>Doxia</b><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><li><b>Mojo</b><p>"Mojo" is really two things when it come
s 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 all non-core Maven plugins. As we try to keep the Mojos as independent of Maven as possible to increase their reuse we try to keep them a bit away from Maven itself. 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><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>
+[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>
</div>
</div>
<div class="clear">
Modified: websites/staging/maven/trunk/content/maven-site-1.0-site.jar
==============================================================================
Binary files - no diff available.