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
Additionally, all individual service repositories hold their own changelog file. At each release
they are bundled in the
When writing changelogs think about to
BREAKING:prefixes to indicate breaking changes.
avoid multi-line statements which include line-breaks. This breaks the release script.
clarity over quantity, because changelogs are for humans.
Changelogs are for humans!
Avoid any technical details on internals. But documenting API or CLI changes are okay. Try to read it from a end-user perspective. page served.
You can find available releases at releases.aura.radio or by
Find releases of individual services in the Gitlab repository page under Deployments > Releases.
Releasing a service
This release step is done by the repository maintainers.
To perform a service release do:
While you should keep the
CHANGELOG.mdup to date at all times, now is a good time to check if you have forgotten something. Also, review if it fits the common format.
In the changelog, update the version from
[Unreleased]to the current version to be released and the current date. Remove all the unused sections. Commit and push.
Bump the version in the file holding the current version. Commit and push the version update.
Release the version by running
make release. This command tags and pushes the current branch.
Then create a new template section with the
[Unreleased]header and all required sections.
As soon a version tag is pushed, the CI/CD Pipeline performs these steps:
Create a GitLab release with the provided
CHANGELOG.mdas its release notes.
Pushes the image to Docker Hub.
Build the Docker Image and automatically tags the release with
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 review their changelogs and do releases of their individual services (see ‘Releasing a service’ above).
Before proceeding also review the main AURA changelog in
Preparing the release
Create a new branch for the release:
git checkout -b %VERSION%-prep. Note the
-prepsuffix for release preparation, as the actual
%VERSION%branch needs to stay unused for the actual release tag branch.
aura/CHANGELOG.mdchange the version identifier
[Unreleased]to the release version and add the current date.
Bump the version of the
poetry version <version>.
Update the versions of referenced services in the Docker Compose
config/<docker compose>/sample.envfiles and in
Update the configuration files and changelogs by running
This command pulls all configuration files and changelogs from the individual repos identified by the versions in
.env.version. The changlogs are stored
.tmpand are merged into a file named
Commit and push the branch.
Now inform the testers to check-out and test the given branch.
Performing the release
After the testers inform the product owner and development team, that the release criteria is met, we can proceed.
In case developers have done any last minute bugfixes and re-released their services, ensure all the configuration and changelog files are still up-to-date by executing
Take the contents of
.tmp/merged-CHANGELOG-%AURA_VERSION%.mdand paste it into a new section in
Now we have to start thinking: What should be in the header of the release notes? Comprehend what this release delivers, by checking the roadmap and contents of the changelog below.
Review and commit the changes.
mainand merge everything changed, except the version updates. They should remain as
mainfor all services. Alternatively cherry-pick the relevant commits or update the relevant version strings to
mainafter the merge.
CHANGELOG.mdwith a new template section for the next release.
Push the changes to
Delete the branch used for release preparation.