docs(release): the rollback section's facts were wrong, and it is the emergency path

§6 and §9 both asserted "latest existing tag is v0.12.0". It is v0.17.4 — twelve
tags newer — and HEAD is 82 commits past that. Everything built on that premise
was therefore wrong at the one moment nobody has time to check it.

**The dangerous half.** §9 argued that a rollback to the previous release could
not even get off the ground: "No v0.12.0 image was ever built or pushed either,
so the pre-pull would fail with `manifest unknown` before you ever got that far."
That presents the registry as a safety net. It is not one. Images for the earlier
v0.17.x releases may well be resident — and after §9's own T-2 pre-pull step, on
the server — in which case the rollback pulls cleanly, starts, and crash-loops on
`VersionMissing` (16 migrations against a database carrying 31) behind a live
Caddy. That is the exact permanent outage §9 exists to prevent, reached through
the one door it said was closed.

Rewritten to say what actually decides: the migration set, checked with
`git ls-tree`, never the registry. A successful `docker pull` is not evidence.
The heading changes from "no older image you can roll back to" to "no released
tag is a VALID rollback target" — older images very probably do exist; what none
of them has is a schema the live database can boot against. The twin-tag scheme
below it was always the right answer and is unchanged.

**The version half.** §6 told you to build and push `v0.17.5`... under the name
`v0.13.0`, which has existed as a git tag since April and carries 6 migrations.
That image would disagree with the tree of the same name, and any host still
pinned to that tag silently swaps builds on its next pull. `.env.example` shipped
`EVENTSNAP_VERSION=v0.13.0` too, and README used a third number (`v0.13.1`). All
three now say v0.17.5 (+ the `-a` rollback twin).

**And the commands now reproduce their own output.** The `git tag` invocation
this commit first reached for returned `archive/pre-squash-20260729`, not
v0.17.4 — the repo carries a non-release tag that sorts first. Both call sites
now use `--list 'v*' --sort=-v:refname`, and all three commands in the §9
evidence block were run and produce exactly what the block claims.

Verified: `git tag --list 'v*' --sort=-v:refname | head -1` → v0.17.4;
`git ls-tree --name-only v0.17.4 backend/migrations/ | grep -c up.sql` → 16;
`git rev-list --count v0.17.4..HEAD` → 82.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
MechaCat02
2026-08-17 17:54:34 +02:00
parent e645d78a6e
commit d270cfcf91
3 changed files with 55 additions and 30 deletions

View File

@@ -161,7 +161,7 @@ Caddy automatically obtains a Let's Encrypt certificate on first start. The app
# ── On your workstation: build and push the new tag ───────────────────────────
# Push the rollback twin at the same time, from the same source — see
# DEPLOYMENT_RUNBOOK.md §9 for why an identical second tag is the rollback target.
VERSION=v0.13.1
VERSION=v0.17.5
docker buildx build --platform linux/amd64 \
-t registry.mc02.dev/eventsnap/app:$VERSION \
-t registry.mc02.dev/eventsnap/app:$VERSION-a --push ./backend
@@ -179,7 +179,7 @@ cd /path/to/eventsnap
git pull
# 3. Point the stack at the new tag.
sed -i 's/^EVENTSNAP_VERSION=.*/EVENTSNAP_VERSION=v0.13.1/' .env
sed -i 's/^EVENTSNAP_VERSION=.*/EVENTSNAP_VERSION=v0.17.5/' .env
# 4. Pull explicitly, BEFORE restarting. A failure here (bad tag, registry down) leaves the
# running stack untouched; letting `up -d` discover it takes the app down first.