Release Management

Semantic Versioning

Release names are defined according to the SemVer 2.0.0 versioning scheme.

Semantic versioning of releases in CI/CD Pipelines

The chosen git tag will be the release name and the version of the Docker Image. Therefore the pipeline script will enforce it to conform to Semantic Versioning 2.0.0.

Keep a Changelog

For changelogs we use the format suggested by Keep a Changelog. Try to follow best practices when writing the changelog. But remember, changelogs are for humans. So do apply best practices when compiling your changelog.

The general AURA changelog is located in CHANGELOG.md.

Additionally, all individual service repositories hold their own changelog file. At each release they are bundled in the aura/changelog directory.

Current Release

You can find available releases at releases.aura.radio or by executing git tag.

Find releases of individual services in the Gitlab repository page under Deployments > Releases.

Release Workflow

Releasing a service

This release step is done by the repository maintainers.

To perform a service release do:

  1. Bump the version in the file holding the current version. Commit the version update.

  2. Release the version by running make release. This command tags and pushes the current branch.

As soon a version tag is pushed, the CI/CD Pipeline performs these steps:

  • Create a GitLab release with the provided CHANGELOG.md as its release notes.

  • Pushes the image to Docker Hub.

  • Build the Docker Image and automatically tags the release with latest and <release version>.

Releasing the AURA software bundle

The release of a complete software bundle is triggered from within the aura repository and performed by the release manager.

Before the bundle can be released, the repository maintainers are informed about a code-freeze in a timely manner and asked to releases their individual services (see ‘Releasing a service’ above).

Preparing the release

  1. Create a new branch for the release: git checkout -b %VERSION%.

  2. Update the versions of referenced services in the Docker Compose config/<docker compose>/sample.env files and in .env.version. Commit the change and publish the branch.

  3. Update the configuration files and changelogs by running make dev.prepare-release.

  4. Bump the version with poetry version <version>.

  5. Commit and push the branch.

Now inform any testers to checkout and test the given branch.

Performing the release

After the tester(s) have informed the product owner and development team, that the release criteria is met, following steps are performed:

  1. Update CHANGELOG.md with relevant information for the release. Check for relevant information to be merged from the individual changelog files in aura/changelogs. The common changelog is also compiled based on entries of the individual service changelogs. These entries are prefixed with the services names.

  2. Review and commit the changes.

  3. make dev.release

  4. Checkout main and merge everything changed, except the version updates. They should remain as unstable. Alternatively cherry-pick the relevant commits.

  5. Update CHANGELOG.md with a new template section for the next release.

  6. Push the changes to main.

  7. Delete the branch used for release preparation.