Releasing a new version

This page describes the various steps to prepare and create a new release of the application. A new release consists of merging changes into the main branch, creating a new git tag. The flow will also automatically trigger a build of a corresponding Docker image on DockerHub.

We do NOT use GitHub Releases as they are not transferrable. Instead, we keep a CHANGELOG document.

Step 1: Update the CHANGELOG document

Update the CHANGELOG document in the dev branch, close the current unreleased cycle by assigning it the next version number. Create a new empty unreleased cycle which will be used to log new, future changes after the tag has been created and deployed.

Step 1: Merging into the main branch

All development happens on the dev branch. Releases are created from the main branch. It is assumed that the main branch is stable / never breaking. As our development practices as well as the overall architecture evolves and settles, adding automated tests will help ensure this.

When the team has asserted that a release is due and the development branch is stable enough:

git checkout dev
git pull origin dev
git checkout main
git pull origin main
git merge dev

Step 2: adding & pushing a git tag

We adhere to semantic versioning in a pragmatic fashion. Releases are tagged according to the scheme vXX.YY.ZZ where XX is a Major version (incompatible), YY is a Minor version (backward compatible) and ZZ is a Patch version (bug versions).

git fetch
git tag v1.0.12
git push --tags
git push origin main

Pushing a commit or git tag will trigger the build process on DockerHub, creating a new Docker image for the corresponding branch or tag.