Update the release captain howto to the latest workflow.

Signed-off-by: Volker Theile <vtheile@suse.com>

docs/decisions/0004-release-captain.md

@@ -16,34 +16,82 @@ taking appropriate measures to include all necessary fixes and features as well
 as delivering sane and functional container images. The release captain is also
 responsible for describing the changes of the new release in the release notes.
 
+### Prepare a Release
+
+For the testing phase that is done right before the official release, the
+following actions need to be done.
+
+- Create a branch for a given release in the `ceph`, `s3gw`, `s3gw-ui`,
+  `s3gw-tools` and `s3gw-charts` repositories. This can be done easily via
+  the GitHub branches page. E.g. visit the [s3gw-ui branches][1] page, click
+  the `New branch` button and enter `v0.8.0`.
+  All bugfixes will be done in the `main` branches of the sub-projects and
+  then backported to the `vx.y.z` release branch afterwards. The name of the
+  branch should reflect the current milestone (i.e. `v0.8.0`).
+  In the `ceph` repository we need to prepend `s3gw-` (i.e. `s3gw-v0.8.0`).
+
 ### Create a Release
 
-- Create a release branch for a given release for the `ceph` & `s3gw-ui`
-  repositories. All bugfixes will be backported to the relevant repo. The name
-  of the branch should reflect the current milestone (ie `0.8.0`). In the Ceph
-  repo we need to prepend `s3gw-`(ie `s3gw-0.8.0`)
-- Aggregate changelog and create s3gw/docs/release-notes/s3gw-vx.x.x.md Use
-  previous release notes for guidance.
-- Change s3gw/docs/release-notes/latest to point to the new release notes (this
-  will be used by automation)
-- Update all subrepos changelog from `Unreleased` to the current release date.
-- Bump all subrepos repos to the desired git ref
-- Push these changes
-- Create a version tag in the s3gw repo (this triggers the release pipeline,
-  which creates the container and a draft release)
+After the testing phase the following actions need to be done:
+
+- Update the changelog from `Unreleased` to the current release date for each
+  sub-project `s3gw-ui`, `s3gw-tools` and `s3gw-charts`. Create a PR for the
+  `vx.y.z` release branch of each sub-project including these changes. After
+  these PRs have been merged, the changes in the release branch of each
+  sub-project need to be merged into their `main` branch, e.g.:
+
+  ```shell
+  cd ~/git/s3gw-ui
+  git checkout main
+  git merge "v0.8.0"
+  ```
+
+- Aggregate the changelog and create `s3gw/docs/release-notes/s3gw-vx.x.x.md`.
+  Use previous release notes for guidance.
+- Change `s3gw/docs/release-notes/latest` to point to the new release notes
+  (this will be used by automation).
+- Bump all branches in `s3gw/.gitmodules`.
+- Push these changes via PR into the `vx.y.z` release branch.
+- After the PR has been merged, create an annotated and signed [version tag][2]
+  `vx.y.z` in the `s3gw` repository (this triggers the release pipeline, which
+  creates the container and a draft release).
+
+  ```shell
+  cd ~/git/s3gw
+  git checkout "v0.8.0"
+  git tag -a -s "v0.8.0"
+  ```
+
+- Merge the changes of the `vx.y.z` release branch into `main`.
+
+  ```shell
+  cd ~/git/s3gw
+  git checkout main
+  git merge "v0.8.0"
+  ```
+
+- Create a [draft release][3] and choose the previously created tag.
+  File the form with the following data:
+  - Use `vx.y.z` as title.
+  - Paste the content of `s3gw/docs/release-notes/s3gw-vx.x.x.md` as
+    release notes.
 - After waiting for the release pipeline to finish building, go to the release
-  page and make the release public
+  page and make the draft release public.
 
 ### Sanity Checks
 
-- s3gw container published (ghcr.io/aquarist-labs/s3gw:vx.x.x)
-- s3gw-ui container published (ghcr.io/aquarist-labs/s3gw-ui:vx.x.x)
-- The container tags ghcr.io/aquarist-labs/s3gw:latest and
-  ghcr.io/aquarist-labs/s3gw-ui:latest should exist and point to their
+- `s3gw` container published (ghcr.io/aquarist-labs/s3gw:vx.y.z).
+- `s3gw-ui` container published (ghcr.io/aquarist-labs/s3gw-ui:vx.y.z).
+- The container tags `ghcr.io/aquarist-labs/s3gw:latest` and
+  `ghcr.io/aquarist-labs/s3gw-ui:latest` should exist and point to their
   respective latest container.
-- Chart updated
-- Release notes
+- Chart updated.
+- Release notes.
 
 ## Decision Outcome
 
 The proposed steps are approved and this document can be used as reference.
+
+[1]: https://github.com/aquarist-labs/s3gw-ui/branches
+[2]: https://git-scm.com/book/en/v2/Git-Basics-Tagging
+[3]: https://github.com/aquarist-labs/s3gw/releases/new