Rules for Semantic Versioning

Why Semantic Versioning?

[Work in progress]

A good versioning policy can help to reduce dependency hell and therefore we use Semantic Versioning.

Version numbers are intended to identify the development state of a software system but they are also used for commercial, psychological and cultural purposes and that reduces their effectiveness. The key idea of semantic versioning (to save you a click to the above web site) is to change version numbers based on strict criteria:

• the MAJOR version changes when an incompatible API change has been made,
• the MINOR version changes when backwards-compatible functionality has been added, and
• the PATCH version changes when a backwards-compatible bug fix has been made. Additional labels for pre-release and build meta-data are available as extensions to the MAJOR.MINOR.PATCH format.

For users of UseTheSource software this means less surprises and better working software. For UseTheSource developers it requires a modest amount of extra planning and reflection.

For UseTheSource Developers

We recommend the following semantic versioning conventions:

• For prerelease meta-data use strings of the form alpha.1, alpha.2, beta.1, beta.2, rc.1, rc.2 and so on. Make sure that these strings are alphabetically increasing. Remove the prerelease meta-data when you actually release your software.
• For build meta-data use a time stamp of the build, e.g., 20160215.

During development version numbers will look like 1.2.3-alpha.2+20160215 and after deployment 1.2.3 (or 1.2.3+20160215 but only when really needed, for instance on a site with previous releases)

Frequently asked Questions

• Which development scenarios work best with semantic versioning? Suppose you have just released 1.2.3 and development of the next major release 2.0.0 starts. Now there are two scenarios [TBD: we have not yet figured out which one works best for us]:

  Scenario 1. Create a new branch labeled 1.2.3 and perform bug fixes there. Work on the next main release continues on the main branch.

  Scenario 2. The reverse of scenario 1: do bug fixing on the main branch and development of the new main release on a separate branch.

• When do you have to change the version number? Certainly not on every commit but at least at release time. A good compromise is to use a version 2.0.0-alpha.N for increasing Ns.

• What to do to if I want to release a part of the new main release before it is ready? Depending on the scenario you use, backport the functionality to the branch corresponding to the already released version and release with an appropriate semantic version number. This may force you have a 2.0.0 release much earlier than anticipated.

• Where can I find the version in the source? [TBD]

Resources for Semantic Versioning

• Semantic Versioning Home Page
• Wikipedia on versioning
• semver: semantic versioning in NPM