Runbook: Release and deploy docs

Runbook: Release and deploy docs

Real runbook — cut a docs release for an application release and ship it. See templates/runbook.md for the upstream template shape.

Summary

When to run

Every time the application repo (rymflux) cuts a release.

Steps

1. Update the changelog. Add a type: changelog entry under docs/user/changelog/ for the release version — title, date, changelog version/category, and a plain-language summary of what changed, migrated, and was deprecated. Merge to main.
2. Build and validate locally.

   pnpm check && pnpm validate && pnpm build

   Fix any broken links or type errors before deploying.
3. Deploy. Pushing to main triggers the GitHub Actions workflow (.github/workflows/deploy.yml), which builds and runs wrangler pages deploy dist --project-name=rymflux-docs. Confirm the run is green.
4. Tag the release. The tag is the reproducible doc snapshot for this app version:

   git tag v0.2.0 && git push origin v0.2.0

5. Verify production.

   curl -s -o /dev/null -w "%{http_code}\n" https://rymflux-docs.pages.dev/

   Spot-check /changelog and any routes touched by the release. Note: bare routes return 308 and follow to their trailing-slash form — that is normal.
6. Write release notes. Create a GitHub Release on rymflux-docs (or rely on the changelog entry) with a human summary, and link the matching application release.

Rollback

Re-promote the previous Cloudflare Pages deployment in the dashboard (Workers & Pages → rymflux-docs → Deployments → ⋯ → Rollback to this deployment). Do not revert git for rollback; fix forward on main.

Escalation

Last tested