Releasing Nuts Node

Nuts Node and auxiliary tools/applications follow a semantic versioning scheme (<major>.<minor>.<patch>(-rc.<rc>)):

Given a version number MAJOR.MINOR.PATCH, increment the: 1. MAJOR version when you make incompatible API changes, 2. MINOR version when you add functionality in a backwards compatible manner, and 3. PATCH version when you make backwards compatible bug fixes.

(Taken from

Note: “API” is a broad term, it covers every interface interacted with by applications or other nodes (including Nuts network protocols).

When a new minor or major version is released, always create a release candidate first: <major>.<minor>.0-rc.1, eg: v5.1.0-rc.1. This version will symbolize a feature freeze and will be used for the first tests. All problems will be fixed and the release candidate version is increased on every bugfix release, eg: v5.1.0-rc.2. When no more problems are found the major/minor version is released without a -rc.<rc> postfix. This approach prevents the docker latest tags to be updated to a new version automatically.

Aside from the Nuts Node itself, all projects that follow the same versions need to be released. They follow the major version from the Nuts Node, but minor and patch versions may differ.

Major release

A major release starts with version number <major>.0.0. Every Nuts Node release has a name (e.g. “Brazil”) and a version number. A release consists of a Git tag and a release in Github with release notes. Releases are created according to the following format:

  • Git tag: v<major>.<minor>.<patch>, e.g. v2.0.0

  • Release name: <name> release (<version>), e.g.: Brazil release (v2.0.0) (every release has a designated name)

  • Release notes: auto-generated by Github.

Bugfix release/patches

When an issue is fixed in a released version a bugfix/patch version must be released. The bug must be fixed on a branch named after the major version, e.g. v1 or v2. The release name follows the release name, but is named “bugfix” instead of “release”. E.g.: Brazil bugfix (v2.0.1).


Bugfixes often need to be backported, e.g. it’s fixed on the master branch but also need to be fixed in the last version, and maybe even in the before last version. Bugfix releases stemming from backports follow the same versioning and naming scheme as regular bugfix releases.