Skip to end of metadata
Go to start of metadata

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

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

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:

Icon

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

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.

Troubleshooting

Sometimes the upload to the Sonatype OSS Nexus fails. This seems to be relatedt to the latest OpenJDK versions, but it's not proven.

If it failed or if the closing of the Staging repository doesn't work, first drop the repository.
Now change to the root directory of the project you are releasing. Inside of it's target folder you'll find a checkout folder. That one does contain the checkout of the tag and is usually used by the maven release:perform plugin.
Change to that folder and do a

and it's probably best to also skip the tests by adding -DskipTests

Icon

If it's now failing to close the repository for certain sha or md5 files go into the subproject folder in question and redo the above call on this one again.

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

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:

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:

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"
Icon

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

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:

Icon

Make sure to include this profile in your Maven installation settings, not in the user settings under ~/.m2. This is because the Maven Release plugin disables all profiles from user settings.

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:

  • No labels