docs: hotfix protocol as an extra document

CLAUDE.md

@@ -71,6 +71,7 @@ docs/                             # user documentation: Sphinx + Markdown (MyST)
 helm-chart/                       # Helm chart; published as an OCI artifact on a v* tag
 CHANGELOG.md                      # user-visible changes; the entry lands in the PR
 RELEASING.md                      # branch model + how a change reaches a cluster
+HOTFIX.md                         # how a fix reaches prod via release/X.Y
 tools/helm/lint-values.yaml       # throwaway values so the chart can be rendered in CI
 tools/nix/                        # Nix flake + process-compose config (toolchain.nix)
 tools/just/*.just                 # just modules — see Dev commands

HOTFIX.md

@@ -0,0 +1,68 @@
+# Hotfixing to the current release branch
+
+The branch model, deployment and changelog rules are in
+[RELEASING.md](RELEASING.md). This is only the hotfix protocol.
+
+## Release branch
+
+For the release that is currently on Prod a release branch is kept:
+`release/0.x`. It starts at tag `v0.x.0`.
+
+## Hotfixes
+
+Hotfixes are tagged `v0.x.1`, `v0.x.2`, etc.
+
+For each hotfix tag, images are built as `release/backend-service:0.x.1` and
+`release/frontend-service:0.x.1`, etc. Once the images are there, the chart can
+be installed on staging and then on prod. Dev does not run release images — it
+follows `main` (see [RELEASING.md](RELEASING.md#dev-follows-main)).
+
+## Order of steps:
+
+### Make the hotfix
+
+Check out the release branch `release/0.x`. It should contain all previous
+hotfix tags.
+
+Make the fix on a `hotfix/some-fix` branch and also add a changelog entry.
+
+### Test the hotfix
+
+Consider that the db schema might have changed and that you have to reset the db
+in order to test the hotfix.
+
+### Merge the hotfix
+
+Open a PR to merge the hotfix into `release/0.x` — not into `main`, which GitHub
+suggests. In the PR, add a second commit that only changes the helm chart
+`helm-chart/Chart.yaml`: from `version: 0.y.m` and `appVersion: "0.x.n"` to
+`version: 0.y.m+1` and `appVersion: "0.x.n+1"`. Merge the PR with "Rebase and
+merge", not "Squash and merge", so the two commits stay separate.
+
+The chart bump belongs in this PR, not in one afterwards: on a release branch CI
+publishes the chart only from tags, so it has to be in the commit that gets
+tagged.
+
+Then update your local release branch, so the release contains the fix:
+
+`git switch release/0.x && git pull --ff-only`
+
+Then `just version::bump patch`. Versions should now all be on `0.x.n+1`.
+
+Push the tag:
+
+`git push && git push origin v0.x.n+1`.
+
+A wrong bump is undone as in
+[If you bumped the wrong way](RELEASING.md#if-you-bumped-the-wrong-way), but
+resetting to `origin/release/0.x` instead of `origin/main`.
+
+The images and the chart should build now. Install the new chart version on
+prod.
+
+### Bring the change to main:
+
+Open a branch from `main` and cherry pick only the fix commit onto that branch,
+not the helm chart commit. `CHANGELOG.md` will conflict: keep the entry, under
+`main`'s own `[Unreleased]`. Open a PR and merge into `main`. Dev gets the fix
+after its next restart.

RELEASING.md

@@ -94,8 +94,8 @@ that exists because a `v*` tag built it.
 Nothing merged to `main` can reach prod. It changes only when someone bumps
 `appVersion`, publishes the chart, and installs that chart version.
 
-While a hackathon is running on prod, install nothing there except hotfixes in
-case the event needs them.
+While a hackathon is running on prod, install nothing there except
+[hotfixes](HOTFIX.md) in case the event needs them.
 
 ## Three version numbers
 
@@ -180,57 +180,9 @@ git tag -d v0.9.0
 
 ## Making a hotfix
 
-A hotfix goes on the release branch prod runs, never through `main`. Take
-`release/0.12` and a fix that becomes `v0.12.2`:
-
-1. **Branch from the release branch**, not from `main`:
-
-   ```bash
-   git fetch origin
-   git switch -c hotfix/thing origin/release/0.12
-   ```
-
-2. **Fix it, in one pull request into `release/0.12`** — set that as the base;
-   GitHub suggests `main`. The pull request carries:
-   - the fix itself,
-   - its line under `[Unreleased]` → `### Fixed` in `CHANGELOG.md`,
-   - the chart bump for the release it will become: `Chart.yaml` `version` up
-     one patch, `appVersion: "0.12.2"`.
-
-   The chart bump belongs here, not in a pull request afterwards: CI publishes
-   charts only for pushes to `main` and for tags, so on a release branch the
-   chart has to be in the commit that gets tagged.
-
-3. **Release it from the release branch**, once the pull request is merged:
-
-   ```bash
-   git switch release/0.12 && git pull
-   just version::bump patch
-   git show                      # read the release commit before it leaves
-   git push && git push origin v0.12.2
-   ```
-
-   The tag builds `release/*:0.12.2`, then publishes the chart from the tagged
-   commit. Installing that chart version on prod is what ships the fix. A wrong
-   bump is undone as [above](#if-you-bumped-the-wrong-way), resetting to
-   `origin/release/0.12` instead of `origin/main`.
-
-4. **Bring the fix to `main`**, or the next minor release brings the bug back.
-   Cherry-pick the fix commit onto a new branch and open a pull request into
-   `main`:
-
-   ```bash
-   git switch -c fix/thing origin/main
-   git cherry-pick --no-commit <fix commit>
-   git restore --source=origin/main --staged --worktree helm-chart/Chart.yaml
-   git commit
-   ```
-
-   Pick only the fix. The hotfix commit also carries the release's chart bump,
-   which is why `Chart.yaml` is put back to `main`'s before committing; merging
-   the release branch into `main` would bring its release commits and changelog
-   headings as well. `CHANGELOG.md` will conflict: keep the entry, under
-   `main`'s own `[Unreleased]`.
+A fix prod cannot wait for goes onto the `release/X.Y` branch prod runs, never
+through `main`. The full protocol — branching, the chart bump, tagging, and
+bringing the fix back to `main` — is in [HOTFIX.md](HOTFIX.md).
 
 ## Making a release deployable