docs: codify release discipline rules + harden release-please config#7
Merged
Conversation
.claude/rules/conventional-commits.md: rewrite to spell out the 5 rules that matter (R1 user-visible change discipline, R2 no empty releases, R3 install scripts as public API, R4 `!` for breaking, R5 release-please owns tags) plus decision matrices for commit-type-by-what-changed and version-bump-by-type, anti-patterns to forbid, and a pre-commit checklist. release-please-config.json: set pull-request-title-pattern to produce clean PR titles (no stray component), and add explicit changelog-sections with hidden flags on ci/chore/docs/build/refactor/test/style. Makes the 'what appears in CHANGELOG' rule explicit and auditable; prevents a future release-please default change from silently polluting history. AGENTS.md / CLAUDE.md: replace the single bump table with the R1-R5 summary and a link into the full rules file. No code behavior change. No version bump expected — this is a `docs:` commit by R1's own definition.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Codifies the discipline we discovered we were missing when v1.1.0 shipped as an "empty" bump (install-script PR + prior CI-only PR typed as `fix:` → triggered release-please → binary byte-identical to v1.0.0).
Two file updates:
.claude/rules/conventional-commits.md — rewrite
Replaces the minimal "here are the types and bumps" doc with:
Key rule that would have prevented v1.1.0: R1 — `feat:` / `fix:` mean user-visible change, not "new thing in the repo." PR #3's `fix: bulletproof watchdog...` touched only `.github/workflows/watchdog.yml` and should have been `ci:`. That alone would have prevented a version bump.
release-please-config.json — hardened
Two adds:
Intentionally not adding `include-paths`. It scopes commit parsing (not just bump filtering), so a `feat:` touching both `src/` and a workflow wouldn't filter correctly. R1+R2 discipline at commit-authoring time is safer.
AGENTS.md / CLAUDE.md
Replaced the bump table with an R1–R5 summary and a link into the full rules file. They remain byte-identical to each other.
Research basis
Audited against astral-sh/uv (user-visible-only CHANGELOG discipline), cli/cli, denoland/deno, and the Conventional Commits v1.0.0 + release-please config schema specs.
No release expected
This is a `docs:` commit per R1's own definition — no bump, no CHANGELOG entry. It's the first commit under the new rules, and the rules predict themselves correctly.
Follow-up
Separate PR will reset release state to a clean v1.0.0 (delete existing v1.0.0 + v1.1.0 tags/releases, reset manifest, `Release-As: 1.0.0`). Safe because adoption is zero (~12h since v1.1.0, no stable install channels caching it). That PR lands only after this one merges.
Test plan