Release doc

docs/releases.md

@@ -1,22 +1,71 @@
 # Release Procedure
 
+# Table of Contents
+
+- [Overview](#overview)
+- [General Information](#general-information)
+- [Automated Release Process (Primary Method)](#automated-release-process-primary-method)
+- [Manual Release Process (Fallback Method)](#manual-release-process-fallback-method)
+
 ## Overview
 
 This document outlines the standard procedure for creating new releases of the STACKIT machine-controller-manager.
 
 ## General Information
 
-- **Versioning:** Versioning follows official [SemVer 2.0](https://semver.org/)
-- **CI/CD System:** All release and image builds are managed by our **Prow CI** infrastructure.
+When releasing machine-controller-manager-provider-stackit, we follow semantic versioning (see https://semver.org/).
+
+For major version changes, the configuration typically needs to be adapted to accommodate breaking changes before successfully upgrading. For minor and patch updates, no configuration adjustments are required.
+
+Both major and minor releases are created from the main branch. Patch releases are created from a release branch that is based on a minor version release.
+
+### Hotfixes
+
+A Hotfix is required when a critical bug or security vulnerability is discovered in a stable version that is currently in production, but the main branch has already moved forward with breaking changes or features not yet ready for release.
+
+We follow a "Fix-First-in-Main" policy. All fixes must be merged into the main branch before being cherry-picked into a specific release branch.
+
+For example:
+
+```mermaid
+gitGraph:
+    commit id: "v1.0.0" tag: "v1.0.0"
+    branch release-v1.0
+    checkout main
+    commit id: "Feature A"
+    commit id: "Breaking Change" tag: "v2.0.0-beta"
+    commit id: "Critical Bugfix"
+    commit id: "Feature B"
+    checkout release-v1.0
+    commit id: "cherry-pick Bugfix" tag: "v1.0.1"
+```
+
+> In the example above, the "Critical Bugfix" cannot be released via the main branch because main contains a "Breaking Change" that isn't ready for general availability. By using a release branch (release-v1.0), we can ship the fix as a patch (v1.0.1) immediately.
+
+1. Create a Pull Request (PR) targeting the main branch. Once reviewed and merged, identify the PR number.
+2. If a branch for your specific minor version (e.g., release-v1.x) doesn't exist yet, create it from the last known stable tag:
+   ```bash
+   git fetch --all --tags
+   git checkout -b release-vx.y vx.y.0
+   git push -u origin release-vx.y
+   ```
+3. Use `/cherry-pick release-vx.y` command in the PR with the changes. The prow will open the cherry-pick PR automatically.
+4. Once the cherry-pick PR has been reviewed, approved, and merged, you can promote the changes by creating a new patch release of machine-controller-manager-provider-stackit.
+   For this, publish the draft release on the `release-vx.y` branch for the next patch version (`vx.y.z`) (see [Publishing a Release](#-publishing-a-release)).
 
 ## Automated Release Process (Primary Method)
 
-The primary release method is automated using a tool called `release-tool`. This process is designed to be straightforward and require minimal manual intervention.
+When changes are merged into `main` or a `release-v*` branch, the `release-tool` creates a draft release to preview the upcoming updates.
+The tool automatically determines the appropriate version tag based on the target branch and the labels of the merged Pull Requests:
 
-1. **Draft Creation:** On every successful merge (post-submit) to the `main` branch, a Prow job automatically runs the `release-tool`. This tool creates a new draft release on GitHub or updates the existing one with a changelog generated from recent commits.
-2. **Publishing the Release:** When the draft is ready, navigate to the repository's "Releases" page on GitHub. Locate the draft, review the changelog, replace the placeholder with your GitHub handle and publish it by clicking the "Publish release" button.
+To publish a release, follow these steps:
 
-Publishing the release automatically creates the corresponding Git tag (e.g., `v1.3.1`), which triggers a separate Prow job to build the final container images and attach them to the GitHub release.
+1. Open the repository's releases page.
+2. Navigate to the corresponding draft release (minor/major for `main`, patch for `release-v*`).
+3. Review to-be-released changes by checking the release notes.
+4. Edit the release by pressing the pen icon.
+5. Change `REPLACE_ME` with your github username.
+6. Press the "Publish release" button.
 
 ## Manual Release Process (Fallback Method)