Versioning

Use Semantic Versioning and Give Your Version Numbers Meaning

It's pretty amazing that in 2017 I still find plenty of projects with no versioning, a random version scheme, or stuck perpetually at 0.1.x. Figuring out the maturity of these projects or the scope of changes between two versions can be terribly difficult. Versioning without any guidelines produces meaningless versions, so we need to follow common guidelines that can make our version numbers meaningful.

Luckily, we have a standard for versioning our software that works quite well: Semantic Versioning (SemVer for short). You've probably seen the SemVer "triple" (e.g. 2.7.0) in your software journeys.

SemVer can be summarized quite simply. Your version is composed of three components: MAJOR.MINOR.PATCH.

There are simple rules that indicate when you must increment each of these versions:

  • MAJOR is incremented when you make breaking API changes
  • MINOR is incremented when you add new functionality without breaking the existing API or functionality
  • PATCH is incremented when you make backwards-compatible bug fixes

Getting Started with SemVer

Semantic Versioning is not complicated, and you can get started by following a small number of guidelines:

  1. New projects start at version 0.1.0
    • You are starting with a set of features, not bug fixes
    • Increment the minor version for each subsequent release
  2. Start versioning at 1.0.0 if:
    • Your software is already used in production
    • Other users depend on your software and care when the API changes
    • You are worrying about backwards compatibility
  3. The initial development phase is represented by MAJOR version 0
    • Make as many breaking changes as you want before v1.0.0
  4. Once you have released v1.0.0, API adjustments or other breaking changes are not acceptable without a new MAJOR version change
  5. If you are adding new features without breaking the existing API or functionality, increment the MINOR number.
  6. If you are fixing bugs, increment the PATCH number.
  7. Avoid making frequent breaking changes unless you absolutely need to!
    • Batch major changes together on a branch until you have enough to justify a new major release

Note well: Keeping a system that's in production or being heavily used at a pre-1.0.0 version is a bad practice. You might as well not be using SemVer at all.

But what if I need additional labels, like "alpha"?

It's pretty common to want to add labels to our builds, to indicate something like a pre-release, alpha, or beta software version.

Semantic versioning supports labels and build metadata as an extension to the MAJOR.MINOR.PATCH format. Simply add a hyphen and identifier to the version number.

For example, say you have a version 1.0.0 candidate ready but want to test it before you make your release. You could label the pre-release versions as follows:

1.0.0-alpha.1
1.0.0-alpha.2

Once you are happy with the stability of 1.0.0, you can make the official release and drop the alpha.x label.

The Semantic Versioning Specification

The Semantic Versioning web page contains the complete specification and answers common questions, so I recommend taking a few minutes to read through it.

Since you're already here, I've included v2.0.0 of the SemVer specification:

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

  1. Software using Semantic Versioning MUST declare a public API. This API could be declared in the code itself or exist strictly in documentation. However it is done, it should be precise and comprehensive.

  2. A normal version number MUST take the form X.Y.Z where X, Y, and Z are non-negative integers, and MUST NOT contain leading zeroes. X is the major version, Y is the minor version, and Z is the patch version. Each element MUST increase numerically. For instance: 1.9.0 -> 1.10.0 -> 1.11.0.

  3. Once a versioned package has been released, the contents of that version MUST NOT be modified. Any modifications MUST be released as a new version.

  4. Major version zero (0.y.z) is for initial development. Anything may change at any time. The public API should not be considered stable.

  5. Version 1.0.0 defines the public API. The way in which the version number is incremented after this release is dependent on this public API and how it changes.

  6. Patch version Z (x.y.Z | x > 0) MUST be incremented if only backwards compatible bug fixes are introduced. A bug fix is defined as an internal change that fixes incorrect behavior.

  7. Minor version Y (x.Y.z | x > 0) MUST be incremented if new, backwards compatible functionality is introduced to the public API. It MUST be incremented if any public API functionality is marked as deprecated. It MAY be incremented if substantial new functionality or improvements are introduced within the private code. It MAY include patch level changes. Patch version MUST be reset to 0 when minor version is incremented.

  8. Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API. It MAY include minor and patch level changes. Patch and minor version MUST be reset to 0 when major version is incremented.

  9. A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. Identifiers MUST comprise only ASCII alphanumerics and hyphen [0-9A-Za-z-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92.

  10. Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version. Identifiers MUST comprise only ASCII alphanumerics and hyphen [0-9A-Za-z-]. Identifiers MUST NOT be empty. Build metadata SHOULD be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence. Examples: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85.

  11. Precedence refers to how versions are compared to each other when ordered. Precedence MUST be calculated by separating the version into major, minor, patch and pre-release identifiers in that order (Build metadata does not figure into precedence). Precedence is determined by the first difference when comparing each of these identifiers from left to right as follows: Major, minor, and patch versions are always compared numerically. Example: 1.0.0 < 2.0.0 < 2.1.0 < 2.1.1. When major, minor, and patch are equal, a pre-release version has lower precedence than a normal version. Example: 1.0.0-alpha < 1.0.0. Precedence for two pre-release versions with the same major, minor, and patch version MUST be determined by comparing each dot separated identifier from left to right until a difference is found as follows: identifiers consisting of only digits are compared numerically and identifiers with letters or hyphens are compared lexically in ASCII sort order. Numeric identifiers always have lower precedence than non-numeric identifiers. A larger set of pre-release fields has a higher precedence than a smaller set, if all of the preceding identifiers are equal. Example: 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0.

Further Reading

Giving Your Firmware Build a Version

Updated: 2019-03-22

Every software product needs a version number. Once bug reports start rolling in, a version number is an absolute requirement for debugging and addressing issues.

In this guide, I describe the details I like to store in each build, how I capture these details, and how I make them available to the firmware.

Table of Contents:

  1. What to Capture
    1. Timestamp
    2. Build Machine
    3. Version
    4. Modifications to Support Windows
  2. Getting Version Into Source
  3. How do I generate my version automatically?
  4. Is there a simpler approach without git tags?
  5. Further Reading

What to Capture

Here are the details I like to log for each build:

  • Time/date of build
  • Machine that built it
  • Version (git tag number)
  • Number of commits away from the last tag
  • Commit hash
  • Dirty or clean build (dirty = local changes that are not committed)

With this set of information, I get a full picture of the build's history and can answer questions such as:

  • Was the build created by the server, or locally by Joe Smith?
  • Is it a clean build, or are there changes that weren't committed?
  • Is it a tagged build, or are there extra commits since the last build?

Timestamp

The easiest way to get the timestamp is to run the date shell command:

$ date
Thu Oct 27 10:27:40 PDT 2016

To include the string in a Makefile:

-DVERSION_BUILD_DATE=\""$(shell date)"\"

Build Machine

For build machine details, I use the whoami and hostname commands:

$ whoami
jenkins

$ hostname
buildbot

I take these two values and combine them into a single string:

jenkins@buildbot

To include the string in a Makefile:

-DVERSION_BUILD_MACHINE=\""$(shell echo `whoami`@`hostname`)"\"

Version

Conveniently, you can get the version information directly from git:

$ git describe --long --dirty --tags
0.1.64-2-gb27efef

Above, 0.1.64 is the latest version tag, 2 indicates that I am two commits ahead of the last versioned build, and the commit hash is at the end.

The simplest approach is to pass the entire git describe output into your version string, but I think it makes your version more confusing to customers, vendors, and CMs. The git describe output is also too verbose if you all you want is to display a marketing version, such as "1.2.64".

I store the following values separately:

  • BUILD_TAG (0.1.64)
  • COMMIT (gb27efef)
  • COMMITS_PAST (2)
  • DIRTY_FLAG (+ if dirty, empty if clean)

Here's some example Makefile code to make these values available:

version := $(subst -, ,$(shell git describe --long --dirty --tags))
COMMIT := $(strip $(word 3, $(version)))
COMMITS_PAST := $(strip $(word 2, $(version)))
DIRTY := $(strip $(word 4, $(version)))
ifneq ($(COMMITS_PAST), 0)
    BUILD_INFO_COMMITS := "."$(COMMITS_PAST)
endif
ifneq ($(DIRTY),)
    BUILD_INFO_DIRTY :="+"
endif

export BUILD_TAG :=$(strip $(word 1, $(version)))
export BUILD_INFO := $(COMMIT)$(BUILD_INFO_COMMITS)$(BUILD_INFO_DIRTY)

This will result in:

Build version: 0.1.64
Build info: gb27efef.2

If the build was dirty, you'd see this instead:

Build info: gb27efef.2+

Modifications to Support Windows

If you're using Windows, you will need to use different commands to get the BUILD_DATE and BUILD_MACHINE variables.

BUILD_DATE := $(shell python -c "from datetime import datetime; print(datetime.utcnow().strftime('%d/%m/%Y, %H:%M'))"
BUILD_MACHINE := $(shell echo %username%)@$(shell hostname)

You can support both Windows and OSX/Linux using shell detection:

ifeq ($(SHELL), cmd.exe)
BUILD_DATE := $(shell python -c "from datetime import datetime; print(datetime.utcnow().strftime('%d/%m/%Y, %H:%M'))"
BUILD_MACHINE := $(shell echo %username%)@$(shell hostname)
else
BUILD_MACHINE := $(shell whoami)@$(shell hostname)
BUILD_DATE := $(shell date -u +"%d/%m/%Y, %H:%M")
endif

Getting Version into Source

Now that we have all the information we want to include for each build available in MAKE variables, we can pass this information to the compiler using compiler definitions.

In your makefile, create a set of definitions for your version library and add them to your CFLAGS:

CFLAGS += -DVERSION_BUILD_DATE=\""$(shell date)"\" \
          -DVERSION_BUILD_MACHINE=\""$(shell echo `whoami`@`hostname`)"\" \
          -DVERSION_TAG=\"$(BUILD_TAG\" \
          -DVERSION_BUILD=\"$(BUILD_INFO)\"

In your source code, refer to these definitions:

void version_print()
{
    printf("%s %s %s (%s)\n", VERSION_BUILD_DATE, VERSION_BUILD_MACHINE, VERSION_TAG, VERSION BUILD);
}

And voilà! you have a version available.

How do I generate my version automatically?

If you're at the stage where you need version builds, you should also be using a CI server such as Jenkins to build your software. These automated build tools will give each build a unique version. You can use the version in your build process.

I create two parametric values for my builds:

  • MAJOR_VERSION
  • MINOR_VERSION

When combined with the Jenkins BUILD_NUMBER variable, you can form your typical version triple by combing them:

${MAJOR_VERSION}.${MINOR_VERSION}.${BUILD_NUMBER}

Resulting in a string like:

1.2.48

The versioning strategy outlined in the article relies on git tags. We'll use temporary tags during the build process to create a clean version number.

Before running the build, I make a temporary local tag:

git tag -a -f -m "Candidate build: ${MAJOR_VERSION}.${MINOR_VERSION}.${BUILD_NUMBER}" ${MAJOR_VERSION}.${MINOR_VERSION}.${BUILD_NUMBER}
make rtos
git tag -d ${MAJOR_VERSION}.${MINOR_VERSION}.${BUILD_NUMBER}

By creating an annotated tag before the build, git describe will work as expected and return a clean "0.1.64" instead of "0.1.63-8". After the build succeeds, push the tag to the host and so it will be available for the next build:

git tag -a -f -m "Successful nightly build ${MAJOR_VERSION}.${MINOR_VERSION}.${BUILD_NUMBER}" ${MAJOR_VERSION}.${MINOR_VERSION}.${BUILD_NUMBER}
git push origin ${MAJOR_VERSION}.${MINOR_VERSION}.${BUILD_NUMBER}

Is there a simpler approach without git tags?

You can pass the ${MAJOR_VERSION}.${MINOR_VERSION}.${BUILD_NUMBER} variables into your make command and utilize those definitions directly:

make rtos BUILD_TAG=${MAJOR_VERSION}.${MINOR_VERSION}.${BUILD_NUMBER}

And:

CFLAGS += -DVERSION_TAG=\"$(BUILD_TAG)\"

However, I always recommend pushing a tag for successful builds. Having each build tagged allows for easier debugging and investigation.

Triggering Version Updates Every Time We Run Make

This versioning scheme works well for build servers, since they are often configured to create versioned builds from a clean slate. However, if you are generating builds from the command line in an incremental manner, the version will not be updated each time you compile.

To trigger a recompilation at every step, we must get our build system to think the file is out of date. Modern build systems, such as Meson, provide options such as build_always_stale which can be used to create a target that is run each build, whether the file is changed or not.

With make, we must perform some trickery to get this to work.

One approach is to touch our version.c file each time we run make:

$(shell touch path/to/version.c)

Another approach is to set version.o to use a PHONY prerequisite which is not connected to a file:

version.o: FORCE

.PHONY: FORCE
FORCE:

Wolfram Roesler describes an alternative approach for setting the version when linking.

Further Reading

Change Log

  • 20190322:
    • Added Further Reading section
    • Added notes on out-of-date versions in CI builds.
    • Add links to other useful articles
  • 20190302:
    • Improved grammar
    • Corrected misspellings
    • Added table of contents
    • Added notes on supporting Windows

Related Articles

Debugging Strategy: Finding Version from a Memory Dump

Have you ever had a device that's in a weird state, and you're curious what version of software is on it so you can load the correct debug symbols? Here's a strategy for figuring that out:

  • Connect to device over JTAG when it's in the desired state
  • Use your JTAG tool to dump the contents of memory into a binary file on your host
    • Example using openocd:
      • dump_image sram.bin 0x300000 0x20000
    • You will need to know where in memory your binary gets loaded, as well as the size of the binary
  • Run strings on the downloaded binary file. You will need to look for something representative for your version string.
    • For example, "buildbot" is the jenkins machine that builds nightly images for my current project.
    • strings sram.bin | grep buildbot
      master 0.1.10 Wed Sep 21 03:10:25 PDT 2016 buildbot@company.io
  • Once you know the version of software you have, you can grab the debug symbols for that build and continue on your merry way.

Happy hunting!