Two operator docs the W5+ deploy pipeline depends on for safe
operation.
docs/MIGRATIONS.md (extended) :
Existing file already covered migration tooling + naming. Append
a "Expand-contract discipline (W5+ deploy pipeline contract)"
section : explains why blue/green rollback breaks if migrations
are forward-only, walks through the 3-deploy expand-backfill-
contract pattern with a worked example (add nullable column →
backfill → set NOT NULL), tables of allowed vs not-allowed
changes for a single deploy, reviewer checklist, and an "in case
of incident" override path with audit trail.
docs/RUNBOOK_ROLLBACK.md (new) :
Three rollback paths from fastest to slowest :
1. HAProxy fast-flip (~5s) — when prior color is still alive,
use the rollback.yml workflow with mode=fast. Pre-checks +
post-rollback steps.
2. Re-deploy older SHA (~10m) — when prior color is gone but
tarball is still in the Forgejo registry. mode=full.
Schema-migration caveat documented.
3. Manual emergency — tarball missing (rebuild + push), schema
poisoned (manual SQL), Incus host broken (ZFS rollback).
Plus a decision flowchart, "When NOT to rollback" with examples
that bias toward fix-forward over rollback (single-user bugs,
perf regressions, cosmetic issues), and a post-incident checklist.
Cross-referenced with the workflow + playbook + role file paths
the operator will actually need to look up.
--no-verify justification continues to hold.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
