Versioning

Versioning

This page describes how we handle versioning at Companion. It will provide information to users how to understand version numbers and information on developers how to generate version numbers.

The main goal of our versioning scheme is to make sure that it is easy for the users of the different parts of Companion to estimate wether different versions are compatible to each other and which impact a different version may have.

Companion is not a monolithic application and different version numbers apply to different parts of the software. Versions must not be redundant, that means for one part of Companion there has to be one place where it's version is stored. If code or functionality is changed, one change must not impact more than one version number.

General scheme

• We use a scheme of three numbers separated by dots. E.g.: 1.23.45
• The three parts are called: major.minor.patch, that means the first number denotes the major-version, the second number the minor-version and the last number the patch-version.
• Each number can only be greater or equal than zero.
• Each number can only be a whole number.
• Each number can only be counted up.
• When one number is counted up, the numbers to the right are reset to zero.
• The first release for the public starts with a major-version of 1.

Version of Companion

We are following the standards given by semantic versioning, adopted for end-user applications. That means wherever semantic versioning relates to an API, we relate to end-user functionality.

• The major-version is counted up if there are breaking changes in the core of companion. E.g.: stored database files will not be usable any more, APIs will not be usable any more
  The major version is not a marketing instrument, we hope to avoid breaking changes as long as possible and so the major version should not change often. This is does not mean lack of innovation and actually less major versions are good.
• The minor-version is counted up if functionality is added or changed in the core of companion or if at least one bundeled module has changed, regardless of how severe the module change is. Added or changed functionality means that there is an intention to add or change functionality which the user can recognize. Typical examples are: a new item, better naming of an item, changed/better color of an item, changed/improved placement, changed behaviour like search giving grouped results instead ungrouped or results with scrollbars instead of no scrollbars.
• The patch-version is counted up if there are changes which do not add or change functionality for the user or the change is that a broken functionality will be fixed. Typical examples are: refactoring code, bundling different versions of libraries or frameworks, fixing a bug without adding new functionality or changing the way it should have been working from the start.
• additionally to the major.minor.patch scheme we are using tags for beta and experimental builds in the form of: major.minor.patch+build-channel-commit
  • build is the integer build number which counts up with every build generated by the Companion build system
  • channel is the release-channel like beta or experimental, it corresponds to the development branch, the stable-channel is not added to the version
  • commit is the hash of the commit head was at when building this version

Version of Companion's APIs

Other applications or modules communicate with Companion by the use of application programming interfaces (APIs). It is the ultimate goal of API versioning to ensure compatibility.
We are strictly following semantic versioning for our APIs.

Version of Modules

We are following the standards given by semantic versioning, adopted for end-user applications. That means wherever semantic versioning relates to an API, we relate to end-user functionality.

• The major-version is counted up if there are breaking changes in the module. E.g.: the module is not compatible to the API used before (common for modules upgraded for Companion v3), the module drops support for a device or a variant of a device, the module changes in a way that stored user data can't be used any more (no upgrade script provided)
• The minor-version is counted up if functionality is added or changed in the module. Added or changed functionality means that there is an intention to add or change functionality which the user can recognize. Typical examples are: a new variable, better naming of an option, changed behaviour like offering variables parsing for textinputs, changed/better sorting of items.
• The patch-version is counted up if there are changes which do not add or change functionality for the user or the change is that a broken functionality will be fixed. Typical examples are: refactoring code, bundling different versions of libraries or frameworks, fixing a bug without adding new functionality or changing the way it should have been working from the start, updating help-file.
• modules are free to add additional tags like build numbers or release channel to their version, however only stable releases with a version of major.minor.patch are bundeled with Companion.