Introduction to Semantic Versioning

Semantic Versioning sounds like one of those phrases designed to make a simple idea wear a tie.

The good news is that the idea underneath it is actually quite simple.

Semantic Versioning, usually shortened to SemVer, is a set of rules for version numbers. A normal version has three parts:

MAJOR.MINOR.PATCH

For example: 2.4.1.

Before anything else: the public API

This bit is important and is sometimes missed in quick explanations of SemVer.

The SemVer specification says software using it must declare a public API. In simple terms, that is the part of your software that other code is expected to depend on.

For a Python library, that might be documented functions and classes. For a command-line tool, it could include documented command options or behaviour. SemVer becomes useful because the version tells people what has happened to that public contract.

Patch

Increase the patch number when you make a backwards-compatible bug fix.

1.4.2 -> 1.4.3

Nice and simple.

Minor

Increase the minor number when you add functionality in a backwards-compatible way.

1.4.3 -> 1.5.0

Notice that the patch number goes back to zero.

Major

Increase the major number when you make incompatible changes to the public API.

1.5.0 -> 2.0.0

This is the warning sign to developers depending on your API: something they use may need changing before they upgrade.

What about version 0?

SemVer treats major version zero as initial development. The public API should not be considered stable.

That makes versions such as 0.1.0 useful while a project is finding its feet, but don't interpret every 0.x project on the planet as following SemVer.

Pre-release versions

1.0.0-alpha
1.0.0-beta.2
1.0.0-rc.1

SemVer allows these identifiers after a hyphen. Pre-release versions have lower precedence than the normal release they belong to.

Build metadata

1.2.3+build.456

Build metadata comes after a plus sign and does not affect version precedence under SemVer. It can still be handy for recording which build produced a package.

Released means released

Once a version has been released, SemVer says its contents must not be modified. If you release 1.2.3 and discover a bug, make a new release. Don't silently replace the download while leaving the same version on it.

Do you have to use SemVer?

No. It is particularly useful when other software depends on your public API. A standalone game or application may decide another scheme communicates its releases better.

But if you tell people your project follows Semantic Versioning, follow the specification rather than a vague approximation. Otherwise you have rather defeated the point!

Have a go

Your library is at 3.2.4.

• You fix a backwards-compatible bug. What should the version become?
• You add a backwards-compatible function. What should it become?
• You remove a documented function users may depend on. Which number changes?

If you answered 3.2.5, 3.3.0 and 4.0.0, you've got the central idea.

Further reading and external resources

If you are going to say your project follows SemVer, read the actual specification.

• Semantic Versioning 2.0.0 specification

Previous: Alpha, beta and release candidate versions | Next: Other ways to version software

Back to Developer Central