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 4.0.0:

  <parent>
    <groupId>org.ops4j</groupId>
    <artifactId>master</artifactId>
    <version>4.2.0</version>
  </parent>
  

• 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.

Prepare the release

From a command line run the following:

mvn release:prepare

Perform the release

From a command line run the following:

mvn release:perform

mvn release:prepare release:perform

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. If the tag has already been pushed to GitHub, use git push origin :refs/tags/myproject-1.2.3 to delete the remote tag after deleting it locally.

Push to Maven Central

The master POM includes the nexus-staging-maven-plugin which is configured to close the staging repository on Sonatype OSS Nexus automatically. It will not automatically release the staging repository, to give you and others a chance to test the staged release before publishing it.

To push the released artifacts to Maven Central, run the following commands:

cd target/checkout
mvn nexus-staging:release

A cron job will push the artifacts to Maven Central within a few hours.

Alternatively, you can log in to Sonatype OSS Nexus to release or to drop the staging repository interactively.

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 ops4j@googlegroups.com.

Appendix A: Maven Profiles

As of org.ops4j:master:3.0.0, you no longer need to enable specific Maven profiles for a release.

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:

<settings>
  <servers>
    <server>
      <id>ossrh</id>
      <username> <!-- your user --> </username>
      <password> <!-- your password --> </password>
    </server>
  </servers>
</settings>

Appendix C: Signing key

We are using GnuPG for signing the artifacts via Maven gpg plugin, this is a requirement of the Sonatype OSS release process.

Generate the private/public key pair

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

gpg --gen-key

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"

Specify your GPG passphrase

At some point in a release build, GPG requires your passphrase, prompting for it on the command line by default. To avoid this prompt, define the following profile in your Maven installation settings $MAVEN_HOME/conf/settings.xml:

<settings>
  ...
  <profiles>
    <profile>
      <!-- Do not change this profile ID -->
      <id>sonatype-oss-release</id>
      <properties>
        <gpg.passphrase> <!-- your key passphrase --> </gpg.passphrase>
      </properties>
    </profile>
  </profiles>
  ...
</settings>

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

mvn release:perform -Darguments=-Dgpg.passphrase=YOURPASSPHRASE

Appendix D: GitHub access

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

ssh-add

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:

mvn ... -Dusername=... -Dpassword=...  release:perform