cnjun / asf-base-pom

Parent POM for ASF java projects that should be distributed through the central Maven repository.

Asf Base POM

Rationale

A base pom codifies policy for projects. It allows a new Maven project to quickly get off the ground and focus on the project itself and not how to build it. The Asf Base POM focus on building libraries and components that are distributed as jar files through the Maven central repository.

It is possible to use the base pom in a new project without any additional changes and modifications.

Preliminaries

The Asf Base POM enforces Maven 3.0.4 or later. The reason for this is http://jira.codehaus.org/browse/MNG-5121 which has only been resolved in version 3.0.4.

By default, the Asf Base POM enforces JDK 1.6. To use another version, add

<properties>
    <project.build.targetJdk>1.7</project.build.targetJdk>
    ...
</properties>

Local setup required!

To fully leverage the deployment options from the Asf OSS POM, a number of servers need to be configured in the local ~/.m2/settings.xml file. If these servers are missing, either artifact or site deployment will fail.

As described on https://docs.sonatype.org/display/Repository/Sonatype+OSS+Maven+Repository+Usage+Guide, the sonatype-nexus-staging and sonatype-nexus-snapshots repositories should be configured:

<servers>
    ...
    <server>
        <id>sonatype-nexus-snapshots</id>
        <username>user</username>
        <password>password</password>
    </server>
    <server>
        <id>sonatype-nexus-staging</id>
        <username>user</username>
        <password>password</password>
    </server>
    ...
</servers>

To support releasing and tagging repositories that are hosted on Github and to allow site deployment to Github, entries for Github and the project site must exist:

<servers>
    ...
    <server>
        <id>github</id>
        <username>github-id</username>
        <password>github-password</password>
    </server>
    <server>
        <id>github-project-site</id>
        <username>git</username>
    </server>
    ...
</servers>

The hard-coded username git and no password for the github-project-site are a limitation of the deployment tool used for the github site. They must exist in the local settings file.

<parent>
    <groupId>net.my.asf</groupId>
    <artifactId>asf-base-pom</artifactId>
    <version> ... current pom release version ...</version>
</parent>

Project pom structure

The following elements should be present in a pom using the Asf Base POM as parent:

• groupId, artifactId, version, packaging, name, description and inceptionYear

  Define the new project. These elements should always be present. If any of those fields are missing from the project, the values from the Asf Base POM are picked up instead.

• scm

  Defines the SCM location and URL for the project. This is required to use the release:prepare and release:perform targets to deploy artifacts to Maven Central.

• organization, developers, distributionManagement

  Empty elements override the values inherited from the Asf Base.

This is a sample skeleton pom using the Asf Base POM:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>net.my.asf</groupId>
        <artifactId>asf-base-pom</artifactId>
        <version> ... current version ...</version>
    </parent>

    <groupId> ... group id of the new project ... </groupId>
    <artifactId> ... artifact id of the new project ... </artifactId>
    <version> ... version of the new project ... </version>
    <packaging> ... jar|pom ... </packaging>
    <description> ... description of the new project ...  </description>
    <name>${project.artifactId}</name>
    <inceptionYear>2013</inceptionYear>
    
    <scm>
        <connection> ... scm read only connection ... </connection>
        <developerConnection>... scm read write connection ... </developerConnection>
        <url> ... project url ... </url>
    </scm>

    <distributionManagement/>
    <developers/>
    <organization/>
    ...
</project>

Project POM conventions

Deploy to Maven Central

Project Build and Checkers

The Asf Base POM hooks various checkers into the build lifecycle and executes them on each build.

Generally speaking, running a set of checks at each build is a good way to catch problems early and any problem reported by a checker should be treated as something that needs to be fixed before releasing.

Checkers are organized in two groups, basic and extended.

Basic checkers

• Maven Enforcer (http://maven.apache.org/enforcer/maven-enforcer-plugin/)
• Maven Dependencies (http://maven.apache.org/plugins/maven-dependency-plugin/)
• Maven Dependency version check (https://github.com/ning/maven-dependency-versions-check-plugin)
• Maven Duplicate finder (https://github.com/ning/maven-duplicate-finder-plugin)

Extended checkers

• Findbugs (http://mojo.codehaus.org/findbugs-maven-plugin/)
• PMD (http://maven.apache.org/plugins/maven-pmd-plugin/)
• License check (http://code.google.com/p/maven-license-plugin/)
• Code coverage (http://www.eclemma.org/jacoco/trunk/doc/maven.html)

All checkers are enabled by default and all checkers will fail the build if a problem is encountered.

Well known dependencies

The Asf Base POM provides a number of dependencies to projects. These dependencies are considered "well known and stable". When a project wants to use any of these dependencies, it can declare them in the project <dependencies> section without a version and automatically pick up a version from the Asf Base POM.

The following dependencies are defined:

Dependency name	Group/Artifact Ids	property
Google Guice	com.google.inject:guice com.google.inject.extensions:guice-servlet com.google.inject.extensions:guice-assistedinject com.google.inject.extensions:guice-multibindings com.google.inject.extensions:guice-throwingproviders	dep.guice.version
Google Guava	com.google.guava:guava	dep.guava.version
Joda Time	joda-time:joda-time	dep.joda.version
Apache Commons Lang 3	org.apache.commons:commons-lang3	dep.commons-lang3.version
Apache Commons Lang	commons-lang:commons-lang	dep.commons-lang.version
Apache Commons Configuratio	commons-configuration:commons-configuration	dep.commons-configuration.version
Apache Commons Codec	commons-codec:commons-codec	dep.commons-codec.version
Apache Commons Collections	commons-collections:commons-collections	dep.commons-collections.version
Apache Commons IO	commons-io:commons-io	dep.commons-io.version
Apache Commons Beanutils	commons-beanutils:commons-beanutils	dep.commons-beanutils.version
Java Inject API	javax.inject:javax.inject	dep.javax-inject.version
Java Servlet API	javax.servlet:javax.servlet-api	dep.javax-servlet.version
slf4j (Simple Logging Facade for Java)	org.slf4j:slf4j-api org.slf4j:slf4j-jcl org.slf4j:slf4j-jdk14 org.slf4j:slf4j-log4j12 org.slf4j:slf4j-nop org.slf4j:slf4j-simple org.slf4j:slf4j-ext org.slf4j:jcl-over-slf4j org.slf4j:jul-to-slf4j org.slf4j:log4j-over-slf4j	dep.slf4j.version
Logback	ch.qos.logback:logback-core ch.qos.logback:logback-classic	dep.logback.version
log4j	log4j:log4j	dep.log4j.version
Findbugs Annotations	com.google.code.findbugs:annotations	dep.findbugs-annotations.version
JUnit testing	junit:junit-dep	dep.junit.version
TestNG testing	org.testng:testng	dep.testng.version
Easymock Mocking framework	org.easymock:easymock	dep.easymock.version
Hamcrest matchers	org.hamcrest:hamcrest-core org.hamcrest:hamcrest-library	dep.hamcrest.version
Objenesis	org.objenesis:objenesis	dep.objenesis.version
Unitils	org.unitils:unitils	dep.unitils.version
Spring	org.springframework:spring-core org.springframework:spring-expression org.springframework:spring-aop org.springframework:spring-context org.springframework:spring-context-support org.springframework:spring-tx org.springframework:spring-jdbc org.springframework:spring-orm org.springframework:spring-oxm org.springframework:spring-web org.springframework:spring-webmvc	dep.spring.version
Dubbo	com.alibaba:dubbo	dep.dubbo.version
Thrift	org.apache.thrift:libthrift	dep.thrift.version
Nifty	com.facebook.nifty:nifty-core com.facebook.nifty:nifty-client	dep.nifty.version
Zookeeper	org.apache.zookeeper:zookeeper	dep.zookeeper.version
Zkclient	com.github.sgroschupf:zkclient	dep.zkclient.version
Fastjson	com.alibaba:fastjson	dep.fastjson.version
Jodd	org.jodd:jodd-core org.jodd:jodd-mail	dep.jodd.version
Velocity	org.apache.velocity:velocity	dep.velocity.version
Bouncycastle	bouncycastle:bcprov-jdk15 bouncycastle:bcpg-jdk15 bouncycastle:bcmail-jdk15	dep.bouncycastle.version
Zip4j	net.lingala.zip4j:zip4j	dep.zip4j.version
Store4j	com.taobao.store4j:store4j	dep.store4j.version