Releases

Version cycle with rc's being optional.

1.0.0 -> 1.0.1-pre1 -> 1.0.1-pre2 -> 1.0.1-rc1 -> 1.0.1-rc2 -> 1.0.1
    patch         build         release      build       release

The pre-releases "pre" and "rc" does not uniquely identify a commit as the same version number may be used for multiple commits. Only final releases (i.e. those without a "pre" or "rc" suffix) are official releases.

By default bumps are committed, but not tagged.
Final releases are tagged and use a different commit message:
```
$ bump2version --tag --message="Release v{new_version}"
```

Pre-release bumps (pre and rc) simply use:

$ bump2version release
# to bump pre -> rc, or
$ bump2version build
# to bump pre1 -> pre2 (or rc1 -> rc2)

To skip rc and make a release directly from "pre" you need to specify the new version like this:

$ bump2version --tag --message="Release v{new_version}" --new-version="x.y.z"

Directly after the release the next commit should bump the version to a pre-release of the next version. The next version should normally be minor version change, until a breaking change is made at which point the major version is bumped.

$ bump2version minor|major

Packaging pre-releases

When packing pre-releases the project should be bumped immediately following the release of the package such that the released package refers to the last commit with that specific version.

For final releases there is no ambiguity as there is only one commit and tag marked with the final version.

Example assuming version 1.1.0-pre1:

Create package for 1.1.0-pre1.
Bump build version 1.1.0-pre1 -> 1.1.0-pre2
```
bump2version build
```

Instructions summary

Assuming starting point is a development version x.y.z-preN this describes the steps involved for a release cycle.

Note: Normally version changes are pushed directly and not merged in to avoid any ambiguities.

Assumptions:

Remote name of central project repository is "upstream"
Releases are made from master (if not simply substitute branch in instructions)

Bump development version (<tt>x.y.z-preN</tt> -> <tt>x.y.z-preN+1</tt>)

Note: The project is still in the development phase here.

Bumping development version can be done after each sprint or when a pre-release package of the project is made.

Fetch & checkout current master

git fetch upstream master
git checkout FETCH_HEAD

Bump x.y.z-preN -> x.y.z-preN+1:
```
bump2version build
```
Inspect changes
```
git show
```
Push version bump directly to upstream:
```
git push upstream HEAD:master
```

(optional) bump major version due to introduction of breaking changes (<tt>x.y.z-preN</tt> -> <tt>x+1.y.z-pre1</tt>)

As project introduced a breaking change this requires a major version bump. The process is the same as "Bump development version" except instead of bumping build we bump major:

Fetch & checkout current master

git fetch upstream master
git checkout FETCH_HEAD

Bump x.y.z-preN -> x+1.y.z-pre1:
```
bump2version major
```
Inspect diff to confirm changes
```
git diff HEAD~
```
Push version bump directly to upstream:
```
git push upstream HEAD:master
```

Bump to release-candidates (<tt>x.y.z-preN</tt> -> <tt>x.y.z-rc1</tt>)

As development phase stops for a planned release and enters quality control, this can be indicated by making release candidate versions which are suffixed with -rcN.

Here we move from x.y.z-preN -> x.y.z-rc1

Fetch & checkout current master

git fetch upstream master
git checkout FETCH_HEAD

Bump x.y.z-preN -> x.y.z-rc1:
```
bump2version release
```
Inspect bump commit to confirm changes
```
git show HEAD
```
Push version bump directly to upstream:
```
git push upstream HEAD:master
```

Bump release-candidate number (<tt>rcN</tt> -> <tt>rcN+1</tt>)

Use same steps as "bump development version".

Final release (<tt>x.y.z-rcN</tt> -> <tt>x.y.z</tt>)

To make a final release of a quality controlled release candidate it involves:

Tagging (signed with e.g. a GPG key)
Custom commit message

and should follow the steps below:

Fetch & checkout current master:

git fetch upstream master
git checkout FETCH_HEAD

Bump to final release:

bump2version --tag --message="Release v{new_version}" release

Inspect release commit to confirm changes:
```
git show HEAD
```
Immediately bump version to next development version:
```
bump2version minor
```
Inspect bump commit to confirm changes:
```
git show HEAD
```
Push release and bump commits to master, as well as the tag:
```
git push upstream HEAD:master
git push upstream refs/tags/vx.y.z
```
To make the tag show up in GitLab release simply edit tag to add release notes.