Clone this wiki locally
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.
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-distributionprofile 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
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
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:
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.