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