From cb722a7fa7ff27ecfeac0f65ac308b932153cd1b Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Thu, 23 Apr 2026 11:08:12 -0700 Subject: [PATCH] docs: versioning invariant in CLAUDE.md Document that VERSION is a monotonic sequence, not a strict semver commitment. Bump level expresses intent; queue-advance within a level is permitted. Prevents future re-litigation of the workspace-aware ship design. Co-Authored-By: Claude Opus 4.7 (1M context) --- CLAUDE.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index d683b907..d7746869 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -407,6 +407,16 @@ No auto-merging. No "I'll just clean this up." ## CHANGELOG + VERSION style +**Versioning invariant (workspace-aware ship).** VERSION is a monotonic ordered +release identifier, not a strict semver commitment. The bump level +(major/minor/patch/micro) expresses intent at ship time. Queue-advancing past a +claimed version within the same bump level is explicitly permitted — if branch A +claims v1.7.0.0 as a MINOR and branch B is also a MINOR, B lands at v1.8.0.0 +(still a MINOR relative to main). Downstream consumers must NOT rely on +"MINOR = feature-only, PATCH = fix-only" as a strict contract. This is why +`bin/gstack-next-version` advances within the chosen bump level rather than +repicking the level when collisions happen. + **VERSION and CHANGELOG are branch-scoped.** Every feature branch that ships gets its own version bump and CHANGELOG entry. The entry describes what THIS branch adds — not what was already on main.