Maven Best Practice

The following guidelines will make your Maven builds easier to follow and make John and Catherine love you forever.

• Implement all the standard Astrogrid Goals (http://www.astrogrid.org/maven/docs/HEAD/SimpleMavenProject/goalsSummary.html) in your root POM.
• Use Maven 1.0.2 or better.
• Keep your maven.xml simple. Maven should do most of what you need "out of the box".
• There will be occasions when Maven doesn't do what you need and you'll have to write a clever jelly script, but keep it to a minimum since they are difficult for third-parties to maintain.
• Extend the POM in the maven-base project - it has default settings for most things you will need, and you can override any settings that aren't correct for your component. See the POM for the Common component to see how minimal your POM can be.
• Don't override the currentVersion POM property - we need to be able to set this globally in maven-base
• Don't override the other maven-base settings unless you have to - why make work for yourself?
• Set the property astrogrid.name to be the cvs name of your component. This will allow you to use the default cvs repository settings and site doc deployment location from maven-base. See last point.
• When specifying dependencies on astrogrid components, specify a version of ${pom.currentVersion} rather than hardwiring "SNAPSHOT". This will mean that we do not need to edit the POMs when we branch.
• Short project descriptions are fine in the POM, but anything more long-winded should be formatted as an xdoc and placed in the xdocs folder. (See http://www.astrogrid.org/maven/docs/SNAPSHOT/SimpleMavenProject/)
• Describe the packages in your project using the <packageGroups> tag. For example, see Jes Project.xml. This enables javadoc to split the package list into subsections - like this

Multiprojects

• Take advantage of POM inheritance to factor out any commonality in your subprojects (e.g. dependencies) into a parent POM. This POM then in turn inherits from maven-base. Ditto any common properties - see MavenOnePointZeroFeatures.
• Use Maven's multiproject goals to build your project rather than rolling your own (but see MavenOnePointZeroBugs).
• Where applicable, ensure that subprojects can be built in isolation by cd-ing to the sub-project's directory and running the appropriate maven goal. You should either implement the standard astrogrid goals in the subprojects, or clearly document on the index page how to build the subcomponent (is it maven jar? maven war? uberjar?).

For a simple example multiproject, see: http://www.astrogrid.org/maven/docs/HEAD/MultiMavenProject/index.html and the source code at http://www.astrogrid.org/viewcvs/mavenTemplates/MultiMavenProject/

-- JohnTaylor - 16 Jul 2004 Updated -- JohnTaylor - 06 Apr 2005