Release Management

The OneBusAway project is composed of a number of Maven modules. Every once in a while, when the stars and the patches align, a module is deemed ready for an official release. This page attempts to document everything you'll need to perform an official release of a OneBusAway module. Typically, this information will only be useful to a handful of core OneBusAway project managers. For a general discussion of our release management philosophy, see the Governance page.

The typical Maven release process looks like:

mvn release:prepare
mvn release:perform

and it's pretty much the same for OneBusAway. The trick is making sure you have all the proper permissions and credentials to perform the release.

One-Time Setup

Commit Privileges

You'll need commit privileges on the OneBusAway Git repository for the module you wish to release.

Configure your ~/.m2/settings.xml File

You'll need a couple of entries in your ~/.m2/settings.xml Maven settings file.

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                      http://maven.apache.org/xsd/settings-1.0.0.xsd">
  <profiles>
    <profile>
      <id>onebusaway-release</id>
      <properties>
        <gpg.passphrase>########</gpg.passphrase>
      </properties>
    </profile>
    <profile>
      <id>oss-distribution</id>
      <properties>
        <distribution_id>sonatype-nexus-staging</distribution_id>
        <distribution_name>Sonatype Nexus Release Repository</distribution_name>
        <distribution_url>http://oss.sonatype.org/service/local/staging/deploy/maven2/</distribution_url>
        <snapshot_distribution_id>sonatype-nexus-snapshots</snapshot_distribution_id>
        <snapshot_distribution_name>Sonatype Nexus Snapshots Repository</snapshot_distribution_name>
      </properties>
    </profile>
  </profiles>
  <servers>
    <server>
      <id>sonatype-nexus-staging</id>
      <username>contact_onebusaway</username>
      <password>########</password>
    </server>
    <server>
      <id>nexus.onebusaway.org-releases</id>
      <username>deployment</username>
      <password>########</password>
    </server>
    <server>
      <id>developer.onebusaway.org</id>
      <username>dev</username>
      <privateKey>path/to/id_rsa</privateKey>
    </server>
  </servers>
</settings>

This does a couple of things:

• Specifies your GPG passphrase to use when signing releases (more on that later)
• Specifies that when the oss-distribution profile is active, we change the distribution points to be public SonaType open-source Maven repository, which eventual populates the world public Maven repository.
• Specifies the username and password for deployment to the https://oss.sonatype.org/ Nexus staging repository.
• Specifies the username and password for the OneBusAway Maven repository
• Specifies the username and ssh private key for accessing the http://developer.onebusaway.org/ server for deploying site documentation.

To complete your configuration, you will need the following from another OBA maintainer:

• Release passwords (GPG, nexus.onebusaway.org, sonatype-nexus-staging)
• GPG key for signing releases
• OnebusAway SSH Private Key

GPG Key

We sign our Maven releases with a GPG key so that others can verify that they really came from us. You'll need both the OneBusAway public and private key. Once you have them, you import them into your GPG keystore with the following commands:

gpg --import public.key
gpg --allow-secret-key-import --import private.key

If you ever need to export the keys:

gpg --export -a "OneBusAway Contact" > public.key
gpg --export-secret-key -a "OneBusAway Contact" > private.key

Project Configuration

Typically, when working with an existing project, most of the project configuration will have already been taken care of.

Before you Release

Make sure that you have updated any release notes for the project.

Perform a Release

Now that you've got everything ready to go, it's time to perform a release.

mvn release:prepare
mvn release:perform

Stage Release Documentation

After performing a release, it's a good idea to stage the release documentation as well. The easiest way to do so is to start in the root project directory of the Maven project you just released, and execute the following:

cd target/checkout
mvn site-deploy

When performing a Maven release, the release:perform step automatically checkouts the tagged release source code in the target/checkout directory and build the release binaries there. Thus, it's usually a piece of cake to immediately deploy the site documentation from there as well.

• TODO: Maybe building the release documentation and deploying it could be part of the release process automatically? It seems like it should, but it doesn't happen by default.

Release Modules to Global Maven Repository

We additionally release a few specific OneBusAway modules to the global Maven repository such that they can be imported right into projects without requiring the use of the OneBusAway-specific Maven repository.

cd target/checkout
mvn -P oss-distribution,onebusaway-release -DperformRelease=true source:jar javadoc:jar deploy

The current list of globally-released modules includes:

• onebusaway
• onebusaway-collections
• onebusaway-csv-entities
• onebusaway-gtfs-modules
• onebusaway-gtfs-realtime-api
• onebusaway-cli
• onebusaway-maven-skin

You can also see what's actually made it into the public repository at search.maven.org.

The command above deploys the release artifacts to the Sonatype OSS staging repository at https://oss.sonatype.org/. To complete the release, login to the Nexus repository management interface, select "Stating Repositories" and look for the recent org.onebusaway entry. It should have the release artifacts (jar, javadoc, source) for the released module. Assuming it all looks good, first Close the staging repository instance and then Release the staging repository. Only then will the modules actually be released to the global Maven repository.