Versioning

This page contains information on how the versioning problem is handled in the CPF.

Version Tags

The source of a version number is the Git repository that contains the package or CI-repository. During the generate step, The CPF determines the current version number of each package by reading the release version tags of the repository. This version number is then used by the CPF while creating package archives or in the production code. Because of the fully automated versioning-pipeline of a CPF project, developers can rely that builds of two different commits will never have the same version number.

note All repositories that are used for a CPF project should have the release version tag c 0.0.0 at one of their first commits. The CPF requires at least one release version tag for its versioning mechanism to work.

see ref PackageOwnership

Release version format

<b>Format:</b> &lt;major&gt;.&lt;minor&gt;.&lt;patch&gt; <b>Examples:</b> c 1.0.1, c 0.0.99

The version tags must follow the given pattern in order to be recognized by the CPF. Tags of this form are called release versions. The CPF assumes that the commits with the release versions are the ones that are provided to clients. Release version tags must be manually added to the repository when the developer deems a commit worthy to be published. This can also be done via the build-job that is provided by the CPFMachines package.

Internal version format

<b>Format:</b> &lt;major&gt;.&lt;minor&gt;.&lt;patch&gt;.&lt;commit-nr.&gt;-&lt;hash&gt; <b>Examples:</b> c 1.0.1.13-af4d, c 0.0.99.1-3h9k0s

In order to have different version numbers for each build, the CPF will determine internal version numbers for each package whenever the generate step is executed. The first three digits are derived from the latest release version number that can be seen from the current commit in one of its preceding commits. The c <commit-nr.> is the number of commit that have been made since the commit that has the release version. This allows to see if an internal version is older or younger than another internal version. However the commit number alone does not make the version unique, as the development could have branched since the last release version. This could lead to two commits with the same version number. For this reason the version number also contains the first digits of the commit hash. This part will be as long as is needed to make it unique.

Dirty versions

If the repository has local changes that have not yet been committed, the optional c -dirty postfix is added to the version number. Dirty versions can in general not be rebuild by other developers and should therefore not be considered when trying to reproduce bugs.

Using the version number in the production code

For C++ packages, the CPF will automatically generate a header file that contains the current version number. The version can be obtained in the C++ code by using:

#include <MyPackage/cpfPackageVersion_MyPackage.h>

std::string version = mp::getPackageVersion();

assuming that you have a package c MyPackage with namespace c mp.

The package version can be accessed in the c CMakeLists.txt file of the package via the c PROJECT_VERSION variable after the call of the c cpfPackageProject() function if you want to generate your own version files.

Version tags as validation stamps

In the CPF the version tags in the repository are also used to mark commits for which the pipeline target was successfully build. This is only enforced in combination with the build-job that is provided by the CPFMachines package. The build-job adds version tags after successfully building a commit. When this policy is followed, developers can quickly see which commits are worth checking out when they try to build older versions.

Incrementing versions

Version numbers are incremented by adding new release version tags to the repository. This can either be done manually or by setting certain parameters to the build-job that is provided by the CPFMachines package. The CPF assumes that release version tags are unique and ordered, where smaller versions can only be followed by larger versions. Before you manually add a release version tag, you should also make sure that the pipeline target of that commit builds for all your supported configurations.

The build-job of the CPFMachines package will make sure that all of these requirements are met, when incrementing version numbers.

see ref CPFJobSubsection2