From 6dad6741ed9b255f3cc23d0bf0d23b340ccd92d3 Mon Sep 17 00:00:00 2001 From: Julien Herr Date: Mon, 25 May 2026 16:19:22 +0200 Subject: [PATCH] docs(claude): add Releasing guidance to avoid version mistakes Document the -develop/tag-driven release contract in CLAUDE.md so a release is cut correctly: main stays *-develop, the tag is the source of truth, never commit a bare version, and re-bump the next cycle after. Co-Authored-By: Claude Opus 4.7 --- CLAUDE.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 1924d2c..44bbb29 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -200,6 +200,18 @@ MSW (`msw/node`) handles external HTTP mocks. Tests that hit validation paths in - `ADMIN_PASSWORD` is set via `wrangler secret put` — never in config files - Keep `compatibility_date` current on runtime upgrades +## Releasing (read before cutting a release) + +`package.json` `version` is inlined at build time as `APP_VERSION` (`src/config/version.ts`) and surfaced in the admin/status footer, `/health`, and `/api/v1/stats`. **`main` always carries a `-develop` pre-release suffix** (e.g. `0.3.0-develop`) so a dev build is never mistaken for a shipped one. + +When asked to "release X.Y.Z", the **git tag is the source of truth** — do **not** commit a bare `X.Y.Z` to `main`: + +1. Confirm `main`'s `package.json` reads `X.Y.Z-develop` (its base must match the release). If you're bumping the target, that's a separate `-develop` bump. +2. `git tag vX.Y.Z && git push origin vX.Y.Z` — the Release workflow (`.github/workflows/release.yml`) strips the `-develop` suffix in its ephemeral checkout, builds the bundle reporting the bare `X.Y.Z`, and publishes the GitHub Release. It **fails fast** if the tag base ≠ `package.json` base (wrong-commit guard). +3. After the release, reopen the next cycle: `npm version -develop --no-git-tag-version` on `main` (next minor by default, or `X.Y.Z+1-develop` for a patch line), then commit + push. + +Full flow lives in [CONTRIBUTING.md](CONTRIBUTING.md) under "Releasing". + ## When changing behavior **Always document evolutions** — treat docs as part of the change, not a follow-up. When you add or change a feature, update the relevant docs in the same change: