← Home

Break Versioning (BreakVer)

Motivation

Semantic Versioning (SemVer) has some practical issues:

  1. The spec’s too long.
  2. It doesn’t recognise that software breaks are common and not all equal. It’d be nice to distinguish between a major and minor breakage.
  3. It doesn’t recognise psychological/marketing pressures. People strongly resist bumping major version numbers for every breaking change. And sometimes they want to indicate that a change is somehow “significant” even when it’s not breaking.
  4. There’s anarchy pre-v1.0.0. And (2,3) mean that code tends to linger in pre-v1.0.0 for too long.

Net effect: many people using SemVer don’t follow it strictly[1], undermining the value of having a spec in the first place.

[1] If everyone followed SemVer strictly, you’d see a lot more code at version 18.y.z. If you’ve ever released code with ANY breaking change without bumping your major version number, you’ve violated the spec and potentially surprised someone with a breaking change that they weren’t expecting.

Break Versioning spec

As an alternative, I suggest the following trivial spec which I use for my own projects:

<major>.<minor>.<non-breaking>[-<optional-qualifier>]:
------------------------------------------------------
<major>              - Major breaking changes [or discretionary "major non-breaking changes"]
<minor>              - Minor breaking changes [or discretionary "minor non-breaking changes"]
<non-breaking>       - **Strictly** NO breaking changes, ever (!!)
<optional-qualifier> - Tag-style qualifiers: -alpha1, -RC2, etc.

This is intended to be comfortable to follow strictly, so more likely to be reliable in practice:

Bump Implies
<non-breaking> Safe upgrade, always - just do it
<minor> Might break code in a minor way, check CHANGELOG
<major> Might break code in a major way, check CHANGELOG!!

Note that this spec emphasizes the maximum amount of damage a version update could inflict.

There’s only 2 types of version bumps:

  • Those that are definitely safe (non breaking)
  • Those that require checking the CHANGELOG

I want to use BreakVer

Which number should I bump?

Is it possible that your change (bug fix, new feature, whatever) could break anyone’s code?

  • If yes: bump one of <major> or <minor> (your choice).
    A <non-breaking> bump is strictly disallowed!

  • If no: bump one of <major>, <minor>, or <non-breaking> (your choice).

What about changes to broken behaviour or implementation details?

There’s an old joke that every change is breaking for someone.

In practice, most changes are on a spectrum from:

  • “This will catastrophically break all users” to
  • “It’s literally impossible for this change to break anyone”

You’ll need to use your judgement in some cases, but always err on the conservative side. BreakVer’s value comes from the reliability of its <non-breaking> semantics.

Is there a non-trivial likelihood of even approximately reasonable code being broken by the change? If yes, then a <non-breaking> bump is disallowed.

The BreakVer spec will be hosted at: www.taoensso.com/break-versioning 👍