This page documents the OPS4J release process for those OPS4J members that are able to release OPS4J artifacts, such as Alin Dreghiciu, Niclas Hedhman, Toni Menzel, Harald Wellmann and others.

Prerequisites

The OPS4J release process is based on the Maven Release Plugin and Sonatype OSS Repository Hosting which enables us to push all OPS4J artifacts to Maven Central. You need to sign up with Sonatype, read their Usage Guide and get familiar with the Maven Release Plugin before doing your first release.

After signing up, create a ticket in OSSRH JIRA to have your account added to the org.ops4j group to get permissions for the org.ops4j staging repositories.

Then you need to generate a GPG key and set up your GPG passphrase and your Sonatype credentials in your Maven settings.xml. See Appendix B and Appendix C for details.

Before releasing

Before starting the release process ensure that:

• Your Git workspace has no uncommitted changes.
• There are no snapshot dependencies in the project to be released
• Ensure that your main project pom inherits from OPS4J master pom, at least version 2.0.0:
• Your main pom project defines an <scm/> section as below, replacing PROJECT by your actual project name.

  <scm>
    <connection>scm:git:git@github.com:ops4j/PROJECT.git</connection>
    <developerConnection>scm:git:git@github.com:ops4j/PROJECT.git</developerConnection>
    <url>http://github.com/ops4j/PROJECT/tree/master</url>
  </scm>
  

• Make sure your shell can push to GitHub without password prompts, see Appendix D.

There used to be another master POM org.ops4j.pax:master for Pax projects which is now obsolete as all definitions in org.ops4j:master apply to Pax and non-Pax projects alike.

Prepare the release

From a command line run the following:

Perform the release

From a command line run the following:

Once you are familiar with this procedure, you can combine prepare and perform in one step: Doing the two steps separately may help you to troubleshoot problems and rollback.

Troubleshooting

If the release builds fails, you'll have to revert to a pre-release state before trying again. mvn release:rollback or mvn release:clean may help sometimes, but not always.

Make sure that all POMs have SNAPSHOT versions and that the release tag is not set in your Git repository. Use git tag -d myproject-1.2.3 to delete the tag if needed.

Push to Maven Central

To push the released artifacts to Maven Central, log in to Sonatype OSS Nexus to close and release the staging repository. A cron job will push the artifacts to Maven Central within a few hours.

Jira

In the admin section of the released project use the "Release" button to mark the version as released and create the next version. Then close all issues related to just released version using a comment as "Released under x.y".

Change log

Create a change log in the Confluence wiki space of your project. Here is an example from Pax Web. You can include an auto-generated JIRA report of all issues closed for the given releases using the {jiraissues} macro.

Blog entry

Create a Confluence blog entry announcing the release. The announcement should explain the release highlights and a may include a link to change log created in the step above.
Here is an example from Pax Exam.

Make sure to add the labels release and <project name>. This will make your blog entry appear on the OPS4J overview page and on the project homepage by means of a Confluence macro. Check the Pax Exam homepage for an example.

Release announcement

Send a release announcement to ops4j-announcement@googlegroups.com and general@lists.ops4j.org.

Appendix A: Maven Profiles

You need to activate the following Maven profiles when running the Maven Release plugin:

• release
  This will sign all artifacts with your GPG key.
• repos.sonatype.staging
  This will select the Sonatype OSS maven repository for deployment.

There used to be alternative deployment repositories enabled by different profiles. These are now obsolete and we might in fact enable the repos.sonatype.staging settings by default. See Appendix B about getting permissions and setting up credentials for this repository. The Maven Release plugin forks another Maven process. The -Darguments="-Prelease,repos.sonatype.staging" option is required to enable the profiles in the child process.

Appendix B: Authentication

While deploying the artifacts to the specified repositories Maven will use credentials specified in ~/.m2/settings.xml.

Sonatype Nexus authentication

To deploy to Sonatype repositories you will need an account for which you will get an name/password pair. If you do not have an account, sign up with [Sonatype JIRA|JIRA task] and create an issue to have your account added to the org.ops4j.* group.

The JIRA credentials also given you access to the OSSRH Nexus web interface.

Add these credentials to your settings.xml:

Appendix C: Signing key

We are using GnuPG for signing the artifacts via Maven gpg plugin.

Generate the private/public key pair

On *nix run the code bellow and follow the instructions:

We suggest that:

• when gpg asks for e-mail linked to the key you should use the e-mail that you use on the mailing lists
• when gpg asks for comment linked to the key you should use "CODE SIGNING KEY"

If gpg --gen-key appears to hang and complains about missing entropy, open another shell on the same machine and run some disk-bound command like ls -lR /.

Specify your gpg passphrase

While releasing gpg will need your pass phrase, passphrase that you will have to set it in your ~/.m2/settings.xml as follow:

Note that you can also provide the pass phrase via command line:

Appendix D: GitHub access

If your Git workspace is configured to use SSH, make sure that you have an ssh-agent running and call

in your shell before running the Maven Release plugin to avoid prompts during the release process.

Alternatively, if you use HTTPS authentication, specify your credentials via properties when running the Maven Commands: