Java components (Maven)

This document describes the conventions and process used by the OME team for developing and maintaining Java components using Maven as their build system and publishing them to the Central Repository under the org.openmicroscopy namespace.

The set of rules and procedures described below applies to all the following Java libraries.

Component name	GitHub URL	Artifact
OME Common Java library	https://github.com/ome/ome-common-java	ome-common
OME Data model	https://github.com/ome/ome-model	ome-model ome-xml specification
OME JAI	https://github.com/ome/ome-jai	ome-jai
OME POI	https://github.com/ome/ome-poi	ome-poi
OME MDB Tools	https://github.com/ome/ome-mdbtools	ome-mdbtools
OME Stubs	https://github.com/ome/ome-stubs	ome-stubs lwf-stubs mipav-stubs
OME Metakit	https://github.com/ome/ome-metakit	metakit
OME Codecs	https://github.com/ome/ome-codecs	ome-codecs

Note

Some of the historical monolithic Java projects, including Bio-Formats and OMERO, do not strictly comply with these guidelines yet. As the project evolves and components are migrated, any new Java repository should follow this set of rules.

Conventions

Source code and build system

The source code of a Java library should be maintained under version control using Git and hosted on GitHub.

Maven should be used as the primary build system. The directory layout should follow the standard Maven layout i.e. in the case of a single-module project:

pom.xml
src/
  main/
    java/
      <package>
test/
  main/
    java/
      <package>

Additionally, the top-level pom.xml should be structured according to the Maven guidelines.

Development

Java components use Semantic Versioning i.e. given a version number MAJOR.MINOR.PATCH, increment the:

MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards-compatible manner, and
PATCH version when you make backwards-compatible bug fixes.

In between releases the version is bumped to the next SNAPSHOT version.

Code contributions should follow the guidelines highlighted in Code contributions.

Distribution

All the release artifacts for the repositories listed above should be deployed to the Central Repository according to the process described in the next section.

Release process

Maintainer prerequisites

To be able to maintain a Java component, a developer must have:

a GitHub account with push rights to the GitHub source code repository
a Central Portal account registered as an user of the org.openmicroscopy namespace
a valid GPG key for signing the tags and the JARs
a local ~/.m2/settings.xml file configured with an user token generated as described in https://central.sonatype.org/publish/generate-portal-token/

Follow the instructions at https://central.sonatype.org/register/central-portal/ to register to publish via the Central Portal. You need to contact Central Support to be associated with the org.openmicroscopy namespace.

Release strategies

There are different strategies to release a Maven component. At the moment we are pushing 2 successive commits (or Pull Requests) to the master branch. The first commit/Pull Request bumps the version number to the release version and is used for generating the release while the second commit bumps the version to the next development cycle.

Release preparation

The first step of the Java component release is to prepare a release candidate on the GitHub and Central Repository repositories.

The first operation to perform a Maven release is to bump the version out of SNAPSHOT either via editing the pom.xml manually or using the Maven versions plugin:

$ mvn versions:set -DnewVersion=x.y.z -DgenerateBackupPoms=false
$ git add -u .
$ git commit -m "Bump release version to x.y.z"

Additionally, a PGP-signed tag should be created for the released version e.g. using git tag -s:

$ git tag -s -m "Release version x.y.z" vx.y.z

Optionally, push the master branch and the tag to your fork for validation by another member of the team:

$ git push <fork_name> master
$ git push <fork_name> vx.y.z

Once you have updated all the versions and ensured that your build passes without deployment you can perform the deployment by using the release profile with:

$ mvn clean deploy -P release
# Potentially add -D gpg.keyname=keyname if desired.

This will perform validation steps and upload the artifacts to a staging deployment available at https://central.sonatype.com/publishing/deployments.

Publication

At the moment all Java components use the Central Publishing Maven plugin with the auoPublish option set to false. To finish the publication, visit https://central.sonatype.com/publishing/deployments and click Publish.

The GitHub tag can be pushed to the organization repository:

$ git push origin vx.y.z

Next development version

Finally create a commit to bump the new development version e.g. using the Maven versions plugin again and push the master branch:

# Where w == z+1
$ mvn versions:set -DnewVersion=x.y.w-SNAPSHOT -DgenerateBackupPoms=false
$ git add -u .
$ git commit -m "Bump release version to x.y.w-SNAPSHOT"
$ git push origin master

Javadoc

At the moment, we use the service provided https://javadoc.io/ for public hosting of the Javadoc. For each release to Maven Central, the new Javadoc should be automatically deployed within 24h. It is possible to trigger the generation of the Javadoc by visiting the URL.