OpenCPN Developer Manual

Versioning

General

The Shipdriver Templates versioning support consists of some major parts

  • The overall syntax is based on semantic versioning 2.0 as defined in https://semver.org/ with some minor differences, notably a fourth digit

  • The base version defined in Plugin.cmake

  • Automatically assigned unique versions for each build.

  • A possible git tag attached to the commit which overrides all other versioning

  • The Cloudsmith push logic, which selects the repository to use based on the git tag, if any.

These parts could be used in different workflows.

The Syntax

The version syntax is basically

major.minor.patch[.tweak][-prerelease]+[buildinfo_]target

An example:

3.0.1+456.0a59905_flatpak-aarch64-20.08

3.0.1 represents major.minor.patch. The 'tweak' part is not set, it is then 0 and not visible.

A prerelease part like -beta1 is not set.

buildinfo is '456.0a59905', a build number and the git hash (below)

target is 'flatpak-aarch64-20.08'. The last part is a version number, the rest a valid target. The list of valid targets is available in '<target>' in the file ocpn-plugin.xsd.

The Base Version

The base version is setup in Plugin.cmake. It consists of PKG_VERSION and PKG_PRERELEASE.

PKG_VERSION could be set to a value like '3.0.1' or '3.0.1.4' which will go into the base version (above).

PKG_PRERELEASE could be set to a value like 'beta1' which then will make up for a base version like '3.0.1-beta1'.

Automatic Build Info

Without a tag (below) the templates adds a buildinfo part like '456.0a59905_flatpak-20.08-aarch64' which contains a build number, the git commit hash and a target platform. This ensures that different builds always have unique build info which also is sortable.

When a build number is not available, for example in local builds, a timestamp is used instead.

On a sidenote the templates adds more complete build info, usually a link to the ci build, as a comment in the XML metadata.

Git Tags

If a git tag pointing to the commit being built exists, the tag is used as version. This means that the tag completely overrides both the base version defined in Plugin.cmake and the automatic build info.

That is, if the git tag is 1.0.3-alpha1 the version in 1.0.3-alpha1, whatever the contents of Plugin.cmake.

Cloudsmith Uploads

The templates configures three different Cloudsmith repositories. The naming schemes differs somewhat:

  • Commits without a git tag are pushed to the unstable/Alpha repository.

  • Commits with a git tag matching 'beta' or 'rc' is pushed to the Beta repository.

  • Commits with any other tag is pushed to the stable/Prod repository.

How these are configured to actual repositories is described in the Builder Environment Page

Proposed Workflow.

All sorts of versioning schemes are possible using the tools described above. The simplest way (personal view):

  1. Assume we have just released 1.3.2

  2. The new cycle aiming for the 1.3.3 release is started by updating PKG_VERSION to 1.3.3

  3. New commits are added. When there is a need to test, the system generates automatic versions which are perfectly usable, there is no need to touch PKG_VERSION.

  4. The automatic version works both in local and in CI builds. CI builds will pushed to the Cloudsmith Alpha/unstable repository.

  5. When it’s time for the first beta, the commit is tagged with a tag '1.3.3-beta1'. The version then becomes '1.3.3-beta1'. A CI build will be pushed the the cloudsmith beta repository, and the build can be published.

  6. The final release is tagged with '1.3.3'. This then becomes the stable version. The CI build will be uploaded to the stable/Prod repository.

  7. Rinse and repeat.

Other workflows are based on updating PKG_VERSION for each build. The primary drawback is that this means that the version needs to be defined both in Plugin.cmake and the git tag — only the git tag creates a "clean" version without buildinfo.