6. Release Workflow

This document describes everything to know about releases.

Contents

For quick access, use the content links below.

Versioning

This section describes the versioning pattern used for the application. For the KatApp, we use semantic versioning, i.e.:

{major}.{minor}.{patch}

Major

A major release typically contains a whole new set of features, bug fixes, and API changes. Major releases may or may not be backward compatible.

Minor

A minor release typically indicates the addition of new features. However, minor releases should always aim to keep backwards compatibility.

There are some exceptions to this rule, for example alpha or beta releases which are published pre version 1.0.0. Before 1.0.0, minor releases can in fact introduce API breaking changes.

Patch

A patch does not indicate significant code changes. In most cases, a patch describes a bug fix. Usually they do not add any new features. Patches should always be backwards compatible.

Patches can also be used for hot fixes, which may be introduced right after a release.

Changelog

Writing a changelog is essential to keep track of the bug fixes, features and API changes which have been implemented. When adding new entries to the changelog, always insert them at the top. Usually, the changes made in the newest release are the most relevant.

To keep the changelog as uniform as possible, use the following template for new changelog entries:

## <version>

- <api-change>
- <feature>
- <bug-fix>

The most important changes should always be listed first. Thus, API changes or anything that breaks backwards compatibility should be at the top. New features should be listed second, while bug fixes should be listed last.

Here’s an actual example of a new changelog entry:

## 0.1.0

**Release date:** *<date>* \
**Release name:** *<name>*

### API Changes

**Introduced new endpoints:**

- Implemented user registration
- Implemented user login

**Updated existing endpoints:**

- Updated tenant registration
- Updated admin registration

### Features

- Added database transactions
- ...

### Bug Fixes

- Fixed a bug where user could not register
- ...

Checklist

Here’s a checklist of points to keep in mind when releasing a new version:

  • Step 1: Create the release branch

    Create a new release branch using the following naming scheme: release/<version>. Release branches are always created from the develop branch. For more information about branch names, have a look at the git workflow.

  • Step 2: Merge the develop branch

    By now, the develop branch should contain all the changes and bug fixes, which should be part of the release. Then, go ahead and merge the develop branch into the new release branch.

  • Step 3: Update the version number

    On the release branch, update the version number, if not done already. The version number is located in the version file, which itself is located in the root directory of the repository.

  • Step 4: Update the changelog

    In the best case scenario you already updated the changelog along with the features and bug fixes implemented. However, if you did not do that, now is the time to update the changelog file.

  • Step 5: Merge the release branch

    The final step of releasing includes merging the new release branch into the main branch as well as the develop branch. Do not delete the release branch when merging, as it may be subject to further changes in the future. For more information on that, have a look at the git workflow.

Pipelines

Here’s an overview of the pipelines executed during the release process:

  • Build Pipeline:

    The build pipeline is executed whenever you push to one of the following branches:

    • develop
    • release/*
    • feature/*
    • bugfix/*
    • hotfix/*

    The build pipeline must be successful, otherwise you cannot merge a branch.

  • Docker Pipeline (develop):

    The docker pipeline is executed as soon as you push/merge changes to/into the develop branch. This pipeline will build the dev container for multiple platforms. The dev container can be used to extensively test the system.

  • Docker Pipeline (main):

    The docker pipeline is executed as soon as you push/merge changes to/into the main branch. This pipeline will build the production container. Unlike the develop pipeline, this pipeline will publish the container with the latest tag and with a version tag. This is done to keep a container of every released version.

  • Deployment Pipelines (main, develop):

    There are two separate deployment pipelines, one for the main branch, and one for the develop. The pipeline on the main branch will deploy the application to the AWS production stage, whereas the pipeline on the develop branch will deploy the application to the AWS development stage.