------ Development Guide ------ Emmanuel Venisse Trygve Laugstol ------ 8 July 2005 ------ ~~ Copyright 2005 The Apache Software Foundation. ~~ ~~ Licensed 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. Developing Maven 2 This document describes how to get started into developing Maven 2 itself. There is a separate page describing how to {{{building.html}building Maven 2}}. * Finding some work to do 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 help to solve them. The list is on our {{{http://docs.codehaus.org/display/MAVEN/How+to+help}Conflucene wiki}} and will be updated every 60 minutes. JIRA also has RSS feeds available if you'd like to include those in your favorite feed aggregator. We categorize the issues in three different categories: * <>: No previous exposure to the code needed. <({{{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}})> * <>: Exposure to Maven pluins and/or internals required. <({{{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}})> * <>: Good knowledge of Maven internals and it's dependencies required. <({{{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}})> [] 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. * Creating and submitting a patch 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: * Always create the patch from the root of the maven project, i.e. where the pom.xml file is. * Name the file <<-.patch>>>. * When adding the patch add a comment to the JIRA suggesting the commit message. For information on what to include in a commit message please take a look at the existing commit messages. Currently the commit mails are sent to {{{http://mail-archives.apache.org/mod_mbox/maven-dev/}dev@maven.apache.org}} with the subject prefix "svn commit". [] An example on how to create a patch from the command line: --- $ svn diff > MNG-123-maven-core.patch --- 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 <<>> and <<>> commands will only be available if you are on a UNIX platform or using Cygwin on windows. --- $ wget -O - -q | patch -p0 --- If the patch is in a local file <<>> and you want to apply that use this command: --- $ patch -p0 < MNG-123.patch --- A couple of notes: * 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. * Make sure that you follow our code style. * Other useful Subversion commands while developing If you've done a chunk of work and you would like ditch your changes and start from scratch use this command to revert to the original checkout: --- $ svn revert -R . --- The <<<-R>>> argument means that the command will recurse down all directories and revert all changes. Before committing code to the Subversion repository we always set the <<>> property on the directory to prevent some files and directories to be checked in. We always exclude the IDE project files and the <<>> directory. Instead of keeping all of the excludes in mind all the time it's useful to put them all in a file and reference the file with the <<<-F>>> option: --- $ svn propset . svn:ignore -F ~/bin/svnignore --- An example svnignore file: --- target *~ *.log .classpath .project *.ipr *.iws *.iml --- * Related Projects Maven 2 has a few dependencies on other projects. * Plexus 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 2 functionality are Plexus components. You can read more about Plexus {{{http://plexus.codehaus.org}here}}. * Modello 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. You can read more about Modello {{{http://modello.codehaus.org}here}}. * Surefire 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 scriping tests in BeanShell and Jython and has special "batteries" for writing acceptance and functional tests for the web and for testing XML-RPC code. You can read more about Surefire {{{http://surefire.codehaus.org}here}}. * Doxia 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. Currently it has support for these document formats: *---------------------------+----+-----* | Format | In | Out | *---------------------------+----+-----* | APT - Almost Plain Text | Y | N | *---------------------------+----+-----* | DocBook | Y | Y | *---------------------------+----+-----* | FML - FAQ Markup Language | Y | N/A | *---------------------------+----+-----* | LaTeX | N | Y | *---------------------------+----+-----* | RTF | N | Y | *---------------------------+----+-----* | XDoc | Y | Y | *---------------------------+----+-----* | XHTML | Y | Y | *---------------------------+----+-----* Available formats You can read more about Doxia {{{http://doxia.codehaus.org}here}}. * Mojo "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. {{{http://mojo.codehaus.org}The Mojo Project}} 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. * Sub Projects ** Maven SCM 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. ** Maven Wagon 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. * Subversion Configuration Before committing files in subversion repository, you need to read the {{{http://www.apache.org/dev/version-control.html#https-svn}Committer Subversion Access}} document and you must set your svn client with these properties file : {{svn-eol-style.txt}}