C++ components

This document describes the conventions and process used by the OME team for developing, maintaining and releasing its C++ components.

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

Component name GitHub URL CMake project name
OME Common C++ https://github.com/ome/ome-common-cpp ome-common
OME Data Model* https://github.com/ome/ome-model ome-model
OME Files C++ https://github.com/ome/ome-files-cpp ome-files-cpp
OME Qt widgets https://github.com/ome/ome-qtwidgets ome-qtwidgets
OME CMake Superbuild https://github.com/ome/ome-cmake-superbuild ome-cmake-superbuild
OME Files Performance https://github.com/ome/ome-files-performance ome-files-performance
OME Files Python bindings† https://github.com/ome/ome-files-py ome-files-py
*
Contains both Java and C++ code - see Java components
†
Contains both Python and C++ code

Conventions

Source code and build system

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

CMake should be used as the primary build system. There is no standard CMake directory layout. C++-only components like ome-common-cpp use a flattened directory layout:

cmake/
CMakeLists.txt
docs/                    If applicable
  sphinx/
  doxygen/
lib/
test/

Components containing both Java and C++ code like ome-model organize the C++ sources according to the Maven-recommended layout i.e.:

<module>/src/main/cpp             Contains the C++ code
<module>/src/main/java            Contains the Java code

Additionally, header files should be maintained alongside the source files.

Development

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

Code contributions should follow the guidelines highlighted in Code contributions.

Distribution

All the C++ sources and binaries are hosted on the OME downloads according to the process described in the next section.

Release process

Maintainer prerequisites

To be able to maintain a C++ component, a developer must:

  • have a GitHub account and have push rights to the GitHub source code repository
  • have a valid PGP key for signing the tags

Source release

The first step of the C++ component release is to prepare a source release from the Git repository.

Prior to a source release, a PR should be opened and merged to:

  • review the release-version variable in CMakeLists.txt and drop the # unreleased comment
  • update the top-level NEWS.md if it exists with the list of changes and the release date

A PGP-signed tag should be created for the released version e.g. using scc tag-release or more simply git tag -s:

$ scc tag-release -s x.y.z --prefix v

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 the tag is created, run the <COMPONENT>-release job under the Release view tab. This job will create an archive of the repository using git archive:

$ git archive -v --format=tar "--prefix=${project}-${version}/" -o "${dest}/${project}-${version}.tar" "${tag}"
$ xz "{dest}/${project}-${version}.tar"
$ git archive -v --format=zip "--prefix=${project}-${version}/" -o "${dest}/${project}-${version}.zip" "${tag}"

and copy the source archives under https://downloads.openmicroscopy.org/<component>/<version>.

Next development version

Once the release is accepted, the version number of release-version in CMakeLists.txt should be incremented to the next patch number i.e. x.y.z+1 and a suffixed with an # unreleased comment. If a top-level NEWS.md file exists, an entry should be added for the next patch release.

See also

https://github.com/ome/ome-common-cpp/pull/55
Example Pull Request incrementing the patch number of ome-common-cpp and updating NEWS.md following the 5.5.0 source release