Skip to content

Latest commit

 

History

History
48 lines (30 loc) · 3.19 KB

BREAK-VERSIONING.md

File metadata and controls

48 lines (30 loc) · 3.19 KB
Raw

Will try keep this brief/readable :-)

Semantic Versioning can be inadequate in practice. Why?

  1. It doesn't recognise the reality that software breaks are common, and not all equal. It'd be nice to distinguish between a major and minor breakage.
  2. It doesn't recognise the reality of psychological/marketing influences. People strongly resist bumping major version numbers for every breaking change. And sometimes they want to indicate that a change is "significant", even if it's not breaking.
  3. There's anarchy in <v1.0.0. And (1,2) mean that code tends to linger in <v1.0.0 for too long.

Net effect of all this is that in practice most people don't actually use SemVer correctly[1], making Semantic versions ambiguous and therefore pretty unreliable.

This post by Jonathan Ong is great and mostly mirrors my own views on the subject, minus the objection to version qualifiers (which I think serve an important purpose despite their difficulties).

[1] If people were using SemVer correctly, you'd be seeing a lot more code at version 37.y.z. If you've ever released code with ANY breaking change without bumping your major version number, you've technically violated the SemVer contract.

Break Versioning (BreakVer)

As an alternative, I'm suggesting the following variation on SemVer which I'll be using for my own projects in future:

<major>.<minor>.<non-breaking>[-<optional-qualifier>]:
------------------------------------------------------
<major>        - Major breaking changes [or discretionary (qualitative/marketing)].
<minor>        - Minor breaking changes [or discretionary (qualitative/marketing)].
<non-breaking> - **Strictly** non-breaking changes.

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

Bump Can infer
<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!!

It's also simpler, which is nice.

Notice that since we care about the maximum (not minimum) amount of damage a version could inflict, the allowance for discretionary major/minor bumping does not negatively impact our ability to make useful inferences.

I want to use BreakVer. Which number should I bump?

The prescription's intuitive: Is it possible that your change (bug fix, new feature, whatever) could break ANYONE's code? If so, then a <non-breaking> bump is strictly out. Bump one of <minor> or <major>. Otherwise bump one of <non-breaking>, <minor>, or <major>. Choose whichever you think best characterizes the change. That's it!

Note that even in the case of a bug fix, it's still possible for a change to be breaking if there exist people that may be relying on pre-fix faulty behaviour.

Copyright © 2012-2014 Peter Taoussanis. All rights reserved.