Leonardo Izzo
Back to blog
•
5 min read
Count Versioning: Technical Specification

Count Versioning

CountVer is a new versioning system that extends SemVer in a simple way, adding two extra components to provide more information about the release status and the existence of breaking changes.

1. Introduction

CountVer enhances traditional versioning by adding two extra components that provide more detail on the release status and the presence of breaking changes. These components are:

  • A release type (a text tag like beta, alpha, rc) for non-stable releases.
  • A breaker counter for stable releases, indicating how many breaking changes have been introduced.

In stable releases, the breaker counter is used, while in non-stable releases, the release type is displayed instead.

2. Version Format

The release number in CountVer follows this format:

  a.b.c-x/y

Where:

  • a (Major Release):

    • Represents significant changes that could break the API.
    • When a new major version is released, the breaker counter resets. If it resets to 0, it means that the new major release does not introduce additional breaking changes compared to the base version. If it resets to 1 (instead of 0), it indicates that the new major release includes breaking changes.
    • Example: when transitioning from 1.x.x to 2.0.0, it can start as 2.0.0-0 (no breaking changes) or 2.0.0-1 (with breaking changes).

  • b (Minor Release):

    • Represents new features or improvements that maintain compatibility.

  • c (Patch Release):

    • Indicates bug fixes or minor adjustments that do not affect compatibility.

  • x (Release Type):

    • A text tag used only for non-stable releases (e.g., beta, alpha, rc).
    • If omitted, the release is considered stable.

  • y (Breaker):

    • A numeric counter (starting at 0) that increments each time a breaking change is introduced in a stable release.
    • In stable releases, “0” means there are no breaking changes, while “1”, “2”, etc., indicate the number of breaking changes.
    • In non-stable releases (when x is specified), the breaker counter is not used.

3. How It Works

Major Release (a)

  • When to Increment:
    It increases when significant changes that could break API compatibility are introduced.
  • Breaker Reset:
    With each new major version, the breaker counter resets.
    • If it resets to 0, it means the new major release does not introduce additional breaking changes.
    • If it resets to 1 (or another value different from 0), it means that the major release includes breaking changes.

Minor Release (b)

  • When to Increment:
    It increases when adding new features or improvements while maintaining compatibility.
  • Impact on the Breaker:
    The breaker remains unchanged.

Patch Release (c)

  • When to Increment:
    It increases when applying bug fixes or minor adjustments.
  • Impact on the Breaker:
    The breaker remains unchanged unless a breaking change is accidentally introduced.

Release Type (x) and Breaker (y)

  • Non-Stable Releases:
    • A release type is included (e.g., “beta”, “alpha”, “rc”).
    • The breaker counter is not used.
  • Stable Releases:
    • The release type is omitted.
    • The breaker counter is included:
      • a.b.c-0 means no breaking changes.
      • a.b.c-1 means that a breaking change has been introduced.

4. Examples

  1. Stable Release without Breaking Changes:

    • Version: 1.2.3-0
    • Meaning: Version 1.2.3 is stable and does not contain breaking changes.

  2. Stable Release with a Breaking Change:

    • Version: 1.2.3-1
    • Meaning: Version 1.2.3 is stable, but a breaking change has been introduced.

  3. New Major Release without Additional Breaking Changes:

    • Version: 2.0.0-0
    • Meaning: New major release 2.0.0 resets the breaker to 0, indicating that it starts without additional breaking changes.

  4. New Major Release with Breaking Changes:

    • Version: 2.0.0-1
    • Meaning: New major release 2.0.0 starts with a breaker of 1, indicating that the release includes breaking changes in its baseline.

  5. Non-Stable Release (Beta):

    • Version: 1.2.3-beta
    • Meaning: Version 1.2.3 is in beta state; the breaker counter is not used.

5. Benefits

  • Clear Communication:
    Quickly identifies whether a release is stable or non-stable and how many breaking changes have been introduced.
  • Better Dependency Management:
    Tools and processes can use the breaker counter to assess risks when updating.
  • Controlled Evolution:
    Resetting the breaker with each new major release provides a clean start for tracking breaking changes.

6. Conclusion

Count Versioning (CountVer) extends the traditional a.b.c format by adding a release type for non-stable builds and a breaker counter for stable releases. This system helps both developers and users understand the nature and impact of each update, enabling better dependency management and a more controlled evolution of software.