Release Management

Semantic Versioning

Release names are defined according to the SemVer 2.0.0 versioning scheme. The gitlab CI/CD pipeline for releases is configured to only accept tags that conform to this versioning scheme.

Current Release

You can check to learn about the project status & any available releases in our Wiki.

Find releases of the components (Engine, Tank, Steering, etc) on the respective Gitlab repository page under “Deployments -> Releases”. For releases of the pre-configured deployments (Docker Compose) you can look at the releases in the meta repository.

General Release Workflow

Releasing a single component

  1. Note down relevant changes in the CHANGELOG of the components repository (preferably done continuously during development). Try to follow best practices when compiling the CHANGELOG contents.

  2. Decide for a release version (e.g. 1.0.3). You can check which version is the previous one, by reviewing the repositories “Deployment -> Releases” page in the Gitlab UI. The latest release note in the release-notes folder of the repo or the latest git tag represents the most recent version.

  3. Update the version in the application specific version file in the repository and commit the change. For example for Node apps the app version is located in package.json.

All of the following steps should be performed on the latest commit on the main branch:

  1. Add a general description of the release and a release headline for it to the top of the CHANGELOG.

  2. Commit the changes to the repository and the release version as a git tag (the existence of the tag on the remote repository triggers the Gitlab CI/CD pipeline).

  3. Push the changes and the tag.

  4. Wait for the release pipeline to run successfully and check the outcome in the “Deployment -> Releases” page of the repository.

Releasing a software bundle

The release of a complete software bundle is triggered from within the meta repository.

For the meta repository there is the speciality, that you should copy the release notes from the upgraded component releases since the last meta release into the meta release notes.

To document compatible versions of single components, use the <component>_VERSION variables found in the sample.env settings of the docker-compose setups of aura-playout and aura-web.

When is the CI/CD Release Pipeline triggered and what does it do?

The pipeline has two jobs:

  1. It builds and pushes new docker images of the component to the respective AURA Docker Hub Organization.

  2. It creates a release in Gitlab using the content of the CHANGELOG as release notes.

The first job is triggered when a commit is made to the main branch or when a tag is pushed to the Gitlab repository of the component.

When there is a commit on the main branch, the built Docker image will be tagged unstable. Unstable versions can be used in development/testing environments but should not be used in production environments.

When a tag is pushed (technically on any branch, but it should probably be done only on commits on the main branch), the Docker image built will be tagged both latest and <release version>.

When a tag is pushed, and the build/push job is successful, it will then trigger the release job.

Semantic versioning of releases

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.