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++ |
ome-common |
|
OME Data Model* |
ome-model |
|
OME Files C++ |
ome-files-cpp |
|
OME Qt widgets |
ome-qtwidgets |
|
OME CMake Superbuild |
ome-cmake-superbuild |
|
OME Files Performance |
ome-files-performance |
|
OME Files Python bindings† |
ome-files-py |
- *
Contains both Java and C++ code - see Java components (Maven)
- †
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 inCMakeLists.txt
and drop the# unreleased
commentupdate 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
https://ci.openmicroscopy.org/view/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