Semantic versioning for software libraries

Introduction

When you set out to create an application or software library, one of the first things to do is to assign a version number. But... when do we reach version 1.0? It doesn't make sense if we are going to make up the numbers.

Still, this shouldn't be a problem when no one else is affected if you have given your software version 1.0 or 0.1, but nowadays we have great pieces of software called package managers.

For example, npm (package manager for Node.js) is a system by which we can install libraries, which in turn depend on others. These packages may need a specific version, higher or lower than other packages they depend on, and if each owner gives his project the version numbers he wants, it would be chaos.

Semantic versioning

Faced with such a need, semantic versioning was born, a project that aims to solve this dilemma through convention and good practices.

Broadly speaking, SemVer proposes to use X.Y.Z for versioning.

• X: major version. Used when changes are introduced that are not compatible with previous versions.
• Y: minor version. Used when new functionalities are added and compatibility is not broken.
• Z: patch version. Bug fixes compatible with previous versions.

It is also allowed to specify a version name, for example:

• 1.0.1-alpha
• 1.0.1-beta
• 1.0.1-sausages

This means that, for example, if our application uses the "foobar" library, we could update that library without risk as long as the change is a minor or a patch. Very convenient, right?

You can check the rest of the specification as well as a list of frequently asked questions at semver.org.