Skip to main content

Versioning Scheme

The BlackPaw Control System uses semantic versioning for both System Releases and Firmware Releases.

Semantic versioning helps make version numbers easier to understand by showing the scale and type of change in each release.

Version numbers follow this format:

MAJOR.MINOR.PATCH

For example:

  • 1.0.0
  • 1.2.0
  • 1.2.3

What the numbers mean​

Major​

The first number is the major version.

A major version changes when there is a significant change that may not be compatible with earlier versions. This usually means there is a breaking change that may require user action, configuration changes, or a planned upgrade path.

Examples:

  • 1.4.2 → 2.0.0
  • 2.3.1 → 3.0.0

A major release may include:

  • breaking changes
  • removed or replaced features
  • configuration changes
  • compatibility changes
  • migration steps

Minor​

The second number is the minor version.

A minor version changes when new functionality is added in a backwards-compatible way. These releases usually add new features or improve existing behaviour without intentionally breaking supported setups.

Examples:

  • 1.4.2 → 1.5.0
  • 2.0.1 → 2.1.0

A minor release may include:

  • new features
  • new supported devices
  • new options or settings
  • improvements to existing behaviour

Patch​

The third number is the patch version.

A patch version changes when fixes or small improvements are made without changing the overall behaviour of the product in a significant way.

Examples:

  • 1.4.2 → 1.4.3
  • 2.1.0 → 2.1.1

A patch release may include:

  • bug fixes
  • small improvements
  • reliability fixes
  • minor corrections

Pre-release versions​

Pre-release versions may be used for Beta and Edge releases.

These versions include an additional label after the main version number.

Examples:

  • 1.1.0-beta.1
  • 1.1.0-beta.2
  • 1.1.0-edge.1

These labels show that the release is not yet a final Stable release.

Beta versions​

A beta version is typically written like this:

1.2.0-beta.1

This means:

  • the planned stable version is 1.2.0
  • this is an earlier beta build of that release

A later beta might be:

1.2.0-beta.2

Edge versions​

An edge version is typically written like this:

1.2.0-edge.1

This means:

  • the release is part of the Edge track
  • it is an early build ahead of a later Beta or Stable release

Edge version numbering may move quickly and should not be treated as production-ready.

Stable releases​

Stable releases use the normal semantic version format without a pre-release suffix.

Examples:

  • 1.0.0
  • 1.3.0
  • 1.3.4

These are the versions recommended for most users.

System and Firmware versioning​

System Releases and Firmware Releases both use semantic versioning, but they are tracked independently.

This means:

  • a System version and a Firmware version do not need to match
  • a device may use firmware 1.4.2 while the System is on version 2.1.0
  • compatibility should always be checked using the compatibility matrix rather than by assuming version numbers should align

What version numbers do not mean​

Version numbers do not automatically tell you:

  • whether a release applies to Nomad, Helm, or both
  • which devices are supported
  • whether a release requires manual action
  • whether a firmware release is shared or edition-specific

For that information, always check:

  • the release notes
  • the compatibility matrix
  • the device support matrix

Examples​

Example 1​

1.0.0

This is the first stable production release.

Example 2​

1.1.0

This is a minor release with new functionality added in a backwards-compatible way.

Example 3​

1.1.2

This is a patch release with fixes or small improvements.

Example 4​

2.0.0

This is a major release and may include breaking changes or required migration steps.

Example 5​

2.1.0-beta.1

This is the first beta build of a planned 2.1.0 release.

Example 6​

2.1.0-edge.3

This is an Edge build ahead of a later beta or stable release.

How to interpret release notes​

When reading a release note, the version number tells you the scale of change, but not the full impact.

As a rule:

  • major changes deserve extra attention
  • minor changes usually add features or improvements
  • patch changes are usually lower risk
  • beta and edge releases carry more risk than stable releases

Even for patch releases, always review the release note before updating.

For most users:

  • use Stable releases
  • review release notes before updating
  • pay particular attention to major version changes
  • check compatibility before updating System or Firmware