# Release Management ## Semantic Versioning Release names are defined according to the [SemVer 2.0.0](https://semver.org/) versioning scheme. ```{admonition} Semantic versioning of releases in CI/CD Pipelines :class: tip 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](https://semver.org/). ``` ## Keep a Changelog For changelogs we use the format suggested by [Keep a Changelog](https://keepachangelog.com/). 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. When writing changelogs think about to - use **`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. ```{admonition} Changelogs are for humans! :class: alert Avoid any technical details on internals. But documenting API or CLI changes are okay. Try to read it from a end-user perspective. Learn more at [keepachangelog.com](https://keepachangelog.com/). ``` ## Current Release You can find available releases at [releases.aura.radio](https://releases.aura.radio) or by executing `git tag`. Find releases of individual services in the [Gitlab](https://code.aura.radio) repository page under _Deployments > Releases_. ## Release Workflow The release workflow at a glance: 1. Cycle Planning in the beginning of the release cycle: 1. Define the date for code-freeze e.g. Monday evening of the the 6th week. 2. Define the release testers e.g. 1-2 people are sufficient. 3. Define the release date e.g. Thursday of the 6th week. The cooldown phase can be used, when there are huge, unexpected issues. 2. When code-freeze hit, repository maintainers [release their services](#releasing-a-service). When done, they inform the release manager. 3. The release manager starts [preparing the release](#preparing-the-release). When done, the release testers are informed. 4. The release testers start testing, mainly if the suite can be still installed according to the documentation. When issues appear, relevant tickets are re-opened and developers are informed. If successful the product owner and release manager are informed to proceed with the release. 5. The release manager [performs the release](#performing-the-release). Find the detailed steps per role below. ### Releasing a service This release step is **done by the repository maintainers**. To perform a service release do: 1. While you should keep the `CHANGELOG.md` up 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](#keep-a-changelog). 2. 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. 3. Bump the version in the file holding the current version. Commit and push the version update. 4. Release the version by running `make release`. This command tags and pushes the current branch. 5. 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.md` as its release notes. - Pushes the image to [Docker Hub](https://hub.docker.com/u/autoradio). - Build the _Docker Image_ and automatically tags the release with `latest` and ``. ### 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 proceeding review the main AURA changelog in `aura/CHANGELOG.md`. #### Preparing the release 1. Create a new branch for the release: `git checkout -b %VERSION%-prep`. Note the `-prep` suffix for release preparation, as the actual `%VERSION%` branch needs to stay unused for the actual release tag branch. 2. In `aura/CHANGELOG.md` change the version identifier `[Unreleased]` to the release version and add the current date. 3. Bump the version of the `aura` repository with `poetry version `. 4. Update the versions of referenced services in the _Docker Compose_ `config//sample.env` files and in `.env.version`. 5. Update the configuration files, fixtures and changelogs by running ``` make dev.prepare-release ``` This command pulls all configuration files, fixtures and changelogs from the individual repos identified by the versions in `.env.version`. The changlogs are stored `.tmp` and are merged into a file named `merged-CHANGELOG-%AURA_VERSION%.md`. Commit any changed configs and fixtures. 6. 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 ```bash make dev.prepare-release ``` once more. 1. Take the contents of `.tmp/merged-CHANGELOG-%AURA_VERSION%.md` and paste it into a new section in `docs/release-notes.md`. 2. 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. 3. Review and commit the changes. 4. To ship the release, run ```bash make dev.release ``` 5. Check out `main` and merge everything changed, except the version updates. They should remain as `main` for all services. Alternatively cherry-pick the relevant commits or update the relevant version strings to `main` after the merge. 6. Update `aura/CHANGELOG.md` with a new template section for the next release. 7. Push the changes to `main`. 8. Delete the branch used for release preparation. 9. Inform the product owner and team that the release is done.