---------------------------------------------------------------------
Release date: 2017-10-05
Initial release
Releasing a new version
=======================
In this document, we describe how to release a new version of the codebase.
1. Version numbering
First, you must determine the version number for your new release.
For version numbering, we use the [Semantic Versioning 2.0.0 standard][semver].
Briefly, the version number is always MAJOR.MINOR.PATCH (e.g. 0.3.4).
With changes, increment the:
MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards-compatible manner, and
PATCH version when you make backwards-compatible bug fixes.
The bleeding-edge development version is on the [master branch][our repo] of the repository.
Its version number is always of the form `x.y.dev0`.
This version numbering, including the developmental version, is compliant with [PEP440].
Let us suppose you are making a new release `M.N.P`, where `M` is your major version, `N` is your minor version, and `P` is your patch version.
This release may be any of the following:
- A new major release
- A new minor release
- A patch for the latest minor release
- A patch for a pre-existing minor release
The rest of this guide includes code blocks which you can use to automate some of the steps in the release.
To help this process, you can adapt the following code block to declare the version number of your release with the variable `vMNP`.
First declare the variable `vMNP`, such as
sh
vMNP="v0.1.0"
Then run the following code block to assign some other variables based on `vMNP`.
sh
MNP="${vMNPv}"
vMNP="v$MNP"
MNx="${MNP%.*}.x"
vMNx="v$MNx"
echo "\
vMNP = '$vMNP'
MNP = '$MNP'
vMNx = '$vMNx'
MNx = '$MNx'"
2. Collect changes for release
Next, we must create a release candidate branch.