Using Maven for your Jasig project

What is Maven?

The Maven site has a good description of the Maven build management system. http://maven.apache.org/what-is-maven.html

Which Version?

The recommended minimum version of Maven for Jasig projects is Maven 2.2. Maven 3.0 works as well and is recommended for developers cutting releases.

Maven Repositories

All Jasig produced Maven artifacts end up in the central Maven repository. Jasig uses Sonatype's open source repository for publishing snapshots and releases. Sonatype uses a set of rules to make sure the published releases are of good quality and syncs them to the central Maven repository.

Group IDs

Group IDs for Maven projects are important just like package names are for Java classes. The base group ID for all Jasig projects MUST be org.jasig and then depending on what type of project it is another suffix should be added.

Established group IDs:

POM Settings & Configuration

Jasig provides a parent pom which all Jasig projects released using Maven must use. Also when setting up a Jasig Maven project read the Sonatype Maven Documentation about pom.xml setup.

To use the jasig-parent project add the following to the top of your pom.xml:

<parent>
  <groupId>org.jasig.parent</groupId>
  <artifactId>jasig-parent</artifactId>
  <version>35</version>
</parent>

Configure your POM's SCM element:

<scm>
  <connection>scm:svn:https://source.jasig.org/MyProject/trunk</connection>
  <developerConnection>scm:svn:https://source.jasig.org/MyProject/trunk</developerConnection>
   <url>https://developer.jasig.org/source/browse/jasigsvn/MyProject/trunk</url>
</scm>

If your project generates a Maven site use the following distributionManagement configuration and add the profile below.

<distributionManagement>
  <site>
    <id>developer.jasig</id>
    <url>${jasig-site-dist-base}${project-site-path}</url>
  </site>
</distributionManagement>

<profile>
  <id>ci-local-site</id>
  <distributionManagement>
    <site>
      <id>ci-local-site</id>
      <url>${jasig-site-ci-dist-base}${project-site-path}</url>
    </site>
  </distributionManagement>
</profile>

Available Properties

The parent pom defines a number of properties that children can use to help with configuration

Default Settings

The following default settings are included in the Jasig parent project, any of these can be overridden in the child project. The pom source can be viewed from the Central Maven 2 repository: jasig-parent-30.pom

• Organization information
• JASIG License information
• Distribution Management configuration (excluding site)
• JASIG Repository configuration
• Common build plugins
  • maven-source-plugin - attaches source JARs to deployed artifacts
  • maven-license-plugin - allows projects to easily update source license headers and verifies the correct headers are used when releasing
  • maven-notice-plugin - Verifies the NOTICE file for the project exists and contains the correct library references
  • maven-jasig-legal-plugin - Includes the NOTICE and LICENSE files in generated artifacts

Releasing

Before deploying you must read the OSS Repository Hosting documentation from Sonatype. It explains how to use their repository to deploy snapshots and releases.

To ease running the deploy goals the ~/.m2/settings.xml file should be edited and configured for authentication with the Sonatype repository. If you need an account to publish Maven artifacts for your Jasig project please ask the steering committee appropriate for your project.

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

Release Checks

When using the jasig-parent project there are some legal and licensing related checks run on the project during the Maven release project. If any of the checks fail the release will fail and the cause for the failed check will have to be resolved before the release can be cut.

1. License header verification - The maven-license-plugin's check goal is executed to verify all source files have the correct license header.
   • Run mvn license:format to update all source files with the correct header then commit the changes.
2. NOTICE verification - The maven-notice-plugin's check goal is executed to verify the NOTICE file exists and contains entries for all project dependencies.
   • Run mvn notice:generate to generate an updated NOTICE file then commit the change.
3. LICENSE verification - The maven-jasig-license-plugin's copy-files goal is executed which requires a LICENSE and NOTICE file exist for the project. These files are copied into the META-INF directory of the generated artifact.

GPG Signatures

Sonatype requires that all release (not snapshot) artifacts are signed with GPG. Reading How to Generate PGP Signatures with Maven is highly recommended. The Jasig parent pom includes a profile that does this when using the release plugin.