Bare minimum semantic versioning

This covers the bare minimum one needs to know about semantic versioning and how and why to use it.

1. What is Semantic Versioning?

Semantic versioning (semver, colloquially) is a scheme to version software releases.

It divides your version number into three parts: major, minor, and patch.

Changing each of these has a different meaning. In order of decreasing severity:

Major: Increase this when you release a breaking change for any reason. Reset the other two to zero. (1.14.10 ⇒ 2.0.0)
Minor: Increase this when you release a new feature or change an existing behavior in a backwards compatible manner. Reset the minor version to zero. (1.14.10 ⇒ 1.15.0)
Patch: Increase the patch version when you release a bug fix or a security fix in a backwards compatible manner. (1.14.10 ⇒ 1.14.11)

📢 Important

Reserve patch releases exclusively for fixes. Lack-of-feature is not a bug. Use minor releases for those.

2. Unstable software

Semver considers software with major version 0 to be unstable. Once a 1.0.0 release is tagged, the software is considered stable — even if a 2.0.0 release is tagged thereafter.

The rules specified in the previous section apply to stable software only. There are no hard rules for unstable software.

However, it’s a good idea to still follow these rules:

start development at 0.1.0
increment the patch version for releases containing fixes
increment the minor version for all other releases — new features and breaking changes alike
release a 1.0.0 when you’re ready to commit to stability

3. Why, though?

All this ceremony establishes a consistent language between producers and consumers of software about the impact of changes in a release.

It allows producers to establish trust with consumers. This trust makes consumers more likely to upgrade to latest releases, because they know in advance what to expect — they get the following guarantees:

For stable software (1.0 or higher), if a specific release works, newer releases in that major version will also work. They can upgrade to anything with the same major version and get new features and fixes without changing their usage.
For unstable software (lower than 1.0), if a specific version works, they can still upgrade to anything with the same minor version and get fixes.

This trust between producer and consumer is another reason not to violate the rule for patch releases — fixes only.

4. Cost of breaking changes

Semantic versioning gives us a way to categorize the impact of changes in a software release. It gives us a safe way to make breaking changes to our software and communicate the breakage clearly to our consumers — just increase the major version number.

However, it does not make breaking changes any cheaper. The cost of a breaking change — even if semantically versioned — can be really high for some software.

For example, if the software has an ecosystem built on top of it: a few users built some extensions, others built software on top of those extensions, and so on. In such a scenario, a major version bump can leave the ecosystem in a split-brain state. Part of the ecosystem will have upgraded, but others will lag behind for months or years.

Further, if the dependency management system is this ecosystem is strict about version uniqueness, this can also result in an interconnected web of systems all blocked on each other. A system will be blocked on the upgrade until all its dependencies have upgraded, and the consumers of this system will be similarly blocked on it.

For popular software with an ecosystem on top of it, it’s best to avoid major version bumps for as long as possible; or if you must, try to provide a gradual migration path.

5. Conclusion

Semver is great and you should use it, but don’t treat it as a license to make breaking changes.