RackPeek/docs/development/release-guide.md

Release Guide

How to cut a RackPeek release, end to end. The flow is: features → staging (nightly Docker auto-publishes) → main → tagged release.

Everything below happens on staging until the "Merge & publish" step.

---

1. Pre-release checks

• staging CI is green.
• Full suite passes locally: just ci (CLI + discovery + MCP + E2E; rebuilds the Web image).
• Review the release diff: git diff origin/main...origin/staging --stat.

2. Bump the version

Pick the new version per versioning.md (SemVer).

The version is declared in three places — all must agree:

File	Format
RackPeek.Domain/RpkConstants.cs (Version)	v2.2.0 — feeds rpk --version, the web UI header chip, and MCP ServerInfo
RackPeek/RackPeek.csproj (<AssemblyVersion>)	2.2.0
README.md version badge	2.2.0

Also update the version-adjacent extras:

• Shared.Rcl/wwwroot/raw_docs/install-guide.md — pinned release download URLs (tag RackPeek-X.Y.Z, asset rackpeek_X_Y_Z_<rid>).
• .github/workflows/publish-cli.yml and publish-docker.yaml — workflow_dispatch version defaults.

3. Regenerate the CLI docs

rm -rf RackPeek/publish   # REQUIRED: the script reuses a stale binary if one exists
./generate-docs.sh

⚠ generate-docs.sh only publishes the CLI when RackPeek/publish/RackPeek is missing. Skipping the rm regenerates docs from whatever binary is lying around — this has silently dropped new commands before.

Verify:

• git diff Shared.Rcl/wwwroot/raw_docs/cli-commands.md — only expected command changes.
• grep -c '^## ' Shared.Rcl/wwwroot/raw_docs/cli-commands.md matches the header count in cli-commands-index.md.

4. Docs freshness pass

• New user-facing features are mentioned in README.md and Shared.Rcl/wwwroot/raw_docs/overview.md.
• New doc pages are listed in Shared.Rcl/wwwroot/raw_docs/docs-index.json and linked from the README Docs section.
• resource-levels.md sub-resource matrix reflects any new kinds/sub-resources.

Commit everything to staging and let CI run.

5. Merge & publish

1. Open a PR staging → main, wait for CI, merge.
2. From main, dispatch the publish workflows (Actions tab → Run workflow). The version input formats differ per workflow:

Workflow	Version input	Produces
publish-cli.yml	2.2.0 (no v)	Draft GitHub Release tagged RackPeek-2.2.0 with rackpeek_2_2_0_{win-x64,linux-x64,linux-arm64,osx-x64,osx-arm64} binaries
publish-docker.yaml	v2.2.0 (v required, regex-validated)	aptacode/rackpeek:v2.2.0 + :latest (multi-arch)
publish-webui.yml	—	Redeploys the GitHub Pages demo + docs viewer

1. Edit the draft GitHub Release: write the release notes (features, fixes, breaking changes/migrations), then publish it.

6. Post-release verification

• docker pull aptacode/rackpeek:v2.2.0 && docker run --rm aptacode/rackpeek:v2.2.0 rpk --version → v2.2.0.
• Web UI header shows the new version; /mcp still returns 503 without RPK_API_KEY.
• Release-page binary download runs (chmod +x, ./rackpeek --version).
• Docs site reflects the new pages: https://timmoth.github.io/RackPeek/docs/overview

Gotchas

• The nightly Docker image (:nightly, :nightly-<sha>) builds automatically from every push to staging — it is not part of the release flow and is not gated on tests.
• workflow_dispatch runs against the branch you select in the Actions UI — make sure it's main for a release.
• The publish workflows do not read the in-repo version; the operator-typed input is authoritative. Double-check it matches RpkConstants.Version.