From 8d57ae5349c71f6acaab910aa71d33cfc6f0f0c2 Mon Sep 17 00:00:00 2001 From: Toby Hede Date: Mon, 17 Aug 2026 11:07:22 +1000 Subject: [PATCH] docs: stop treating semver as a review concern MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rundown is unreleased with no downstream consumers, which CLAUDE.md already states for persisted runbook state ("compatibility code for consumers that do not exist"). The same reasoning applies to package versions, but it was never written down, so review kept producing semver findings — a changeset bump was recently raised as the top finding on #784 and turned into a PR, for a package nothing depends on. CLAUDE.md gets a `Versioning and changesets` section saying the bump field does not matter, the changeset prose does, and that a finding whose only consequence lands on a hypothetical consumer is out of scope. .coderabbit.yaml gets the same rule twice: in `tone_instructions` for global effect, and as a `.changeset/**/*.md` path instruction that separates the two halves — never comment on the bump level, do review the prose for accuracy against the diff. --- .coderabbit.yaml | 15 +++++++++++++++ CLAUDE.md | 26 ++++++++++++++++++++++++++ 2 files changed, 41 insertions(+) diff --git a/.coderabbit.yaml b/.coderabbit.yaml index 4834252ba..ebb52836a 100644 --- a/.coderabbit.yaml +++ b/.coderabbit.yaml @@ -4,6 +4,10 @@ tone_instructions: >- Focus on type safety, state machine correctness, security policy correctness, persisted state no-migration, CLI output stability, and design principles from CLAUDE.md. Be direct and specific. Flag action-type mapping violations. + This project is unreleased with no downstream consumers: never comment on + semver bump levels, changeset major/minor/patch choices, or breaking-change + impact on hypothetical consumers. A finding whose only consequence lands on a + consumer that does not exist is out of scope. reviews: profile: "assertive" @@ -42,6 +46,17 @@ reviews: - "!**/reports/**" path_instructions: + - path: ".changeset/**/*.md" + instructions: | + Changesets here are release notes, not version metadata. This project is + unreleased and has no downstream consumers. + - NEVER comment on the major/minor/patch bump level. Do not suggest + raising a bump for a breaking change, do not flag a bump as + inconsistent with other changesets, and do not reason about semver + impact on consumers — there are none. + - DO review the prose: is the described change accurate, does it explain + why rather than only what, does it name the defect or behaviour it + affects, and does it match the diff in the same PR. - path: "packages/parser/**/*.ts" instructions: | This is a Markdown runbook parser. Focus on: diff --git a/CLAUDE.md b/CLAUDE.md index 80fb0494f..50856821c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -484,6 +484,32 @@ model, flag reference, and discovery rules. - `NO_COLOR=1` - Disable colored output (standard convention) - `FORCE_COLOR=1` - Force colored output even in non-TTY environments +## Versioning and changesets + +**Rundown is unreleased. Nothing is published, and there are no downstream +consumers.** The same reasoning that retires persisted-state migrations (see +[State Persistence](#state-persistence)) applies to package versions: there is +no one to break. + +Therefore **do not spend effort on semver correctness**, and never raise it as a +review finding. Specifically, none of the following is a defect worth reporting, +a reason to open a PR, or a reason to block one: + +- A `patch` bump on a changeset that removes or changes public API. +- A bump that disagrees with what another changeset chose for a similar change. +- Any argument of the form "a consumer on `^1.0.0` would break" — that consumer + does not exist. + +Write a changeset because it is the release note: it explains **what changed and +why** to the next person reading the history. That prose is worth getting right. +The `major`/`minor`/`patch` field on it is not — pick one and move on. When the +project ships for real, versions start mattering and this section gets deleted. + +The corollary for reviewers, human or agent: **a finding whose only consequence +lands on a hypothetical consumer is out of scope.** Rank findings by whether +they can affect this repo's behaviour, its tests, or a reader's understanding of +the code. Version metadata affects none of the three. + ## CI / Workflow Conventions - **SHA-pinned actions**: GitHub Actions are pinned by commit SHA with a version