From 129682fdd1a638b402d234c013a1f2233ce13061 Mon Sep 17 00:00:00 2001 From: Ryan Lee Date: Mon, 24 Aug 2026 22:51:33 +0000 Subject: [PATCH] chore(changeset): patch intent for the edit-path comment fix and comprehensive README rewrite The edit-path fix merged with no intent, so plan-release read phase=none (v0.1.5 already tagged, zero pending) and shipped it to nobody. This intent moves the next master push to phase=version. Also rewrites .changeset/README.md to a proper human-first guide: - Adds Mermaid state-machine diagram of the release automation contract - Explains the pnpm 11 built-in command and manual markdown structure - Documents the scope rule (Rust crate changes MUST carry intents) - Links directly to the release scripts and workflow definitions - Documents the single-paragraph changelog bullet constraint - Adds callout warning against merging PRs without intents --- .changeset/README.md | 58 +++++++++++++++++++++----- .changeset/edit-path-comment-checks.md | 5 +++ 2 files changed, 52 insertions(+), 11 deletions(-) create mode 100644 .changeset/edit-path-comment-checks.md diff --git a/.changeset/README.md b/.changeset/README.md index ba6d1b8..96998f7 100644 --- a/.changeset/README.md +++ b/.changeset/README.md @@ -1,17 +1,53 @@ # Changesets -This directory holds change-intent files consumed by pnpm-native workspace -versioning (`pnpm version -r`). One file per change, authored with: +> Release intent store and automation contract for `@systemfsoftware/claude-code-comment-checker`. + +This directory holds change-intent files consumed by the release pipeline on pushes to `master`. Every consumer-observable change must record its intent here so the automated release pipeline can bump package versions, generate changelogs, and publish platform binaries. + +```mermaid +flowchart TD + Push[Push to master] --> Plan[plan-release.ts] + Plan -->|Pending .changeset/*.md| Version[phase: version
release-version.ts updates package.json + CHANGELOG.md
Opens changeset-release/master PR] + Plan -->|Untagged manifest version| Publish[phase: publish
Builds platform binaries & publishes npm package
Tags Git release vX.Y.Z] + Plan -->|No intents & version already tagged| None[phase: none
No-op] +``` + +## Quick Start + +Create a markdown file in this directory using pnpm 11's built-in command: ```bash -pnpm change --bump --summary "" [...] +pnpm change --bump --summary "" [@systemfsoftware/claude-code-comment-checker] +``` + +Or write the file manually (`.changeset/.md`): + +```markdown +--- +'@systemfsoftware/claude-code-comment-checker': patch +--- + +Single paragraph in consumer voice explaining what is now observable or fixed. ``` -- A PR that changes a publishable package (`npm/packages/comment-checker`) MUST ship with - an intent here. -- `--bump none` records a change that needs no release (e.g. devDependency or script touch). -- Intents are consumed by the release-versioning workflow (`release-version.yml`) on master - push: it bumps the launcher with the intent's type, writes the CHANGELOG entry, commits, - and tags `vX.Y.Z` — the tag is a by-product of the release. `--bump none` intents are - consumed with no release. -- Standard pnpm 11 native changesets format. +## Intent Rules + +- **Scope includes Rust core changes:** A PR that touches the Rust binary (`crates/comment-checker`) **must** include an intent. The crate compiles into the binary executed by the published npm launcher package; a change in the crate is directly observable by the package consumer. +- **Consumer voice:** Describe what the user of the hook or package observes. Never cite internal file paths, pull request numbers, or test names. +- **Single paragraph body:** The release script ([`scripts/tools/release-version.ts`](../scripts/tools/release-version.ts)) joins all lines in the summary body with spaces into a single changelog bullet item. Do not use multi-paragraph text or markdown sub-bullets. +- **`--bump none` for internal maintenance:** Use `none` only when no observable behavior changed (e.g., devDependency bumps, script edits, workflow refactoring). + +## Release Pipeline Contract + +Release automation is state-driven and runs on push to `master`: + +1. **`phase: version`** — When pending intents exist in `.changeset/`, [`.github/workflows/release.yml`](../.github/workflows/release.yml) executes [`scripts/tools/release-version.ts`](../scripts/tools/release-version.ts), deletes the consumed intents, updates [`npm/packages/comment-checker/package.json`](../npm/packages/comment-checker/package.json) and [`npm/packages/comment-checker/CHANGELOG.md`](../npm/packages/comment-checker/CHANGELOG.md), and creates/updates a release pull request (`changeset-release/master`). +2. **`phase: publish`** — Merging the release PR updates `package.json` on `master` with an untagged version. The subsequent push to `master` enters the publish phase: `release.yml` builds cross-platform artifacts, attaches provenance attestations, publishes to npm, and creates the GitHub tag `vX.Y.Z`. +3. **`phase: none`** — When all intents are consumed and the current manifest version is already tagged, the pipeline exits clean with nothing to do. + +> [!WARNING] +> Merging a pull request without an intent means `plan-release.ts` sees `phase: none`. The changes land on `master` but will never be published to npm or tagged as a release. + +## Contributing + +For general development workflow, gates, and contribution guidelines, see [AGENTS.md](../AGENTS.md) and [CONTRIBUTING.md](../CONTRIBUTING.md). diff --git a/.changeset/edit-path-comment-checks.md b/.changeset/edit-path-comment-checks.md new file mode 100644 index 0000000..63f9998 --- /dev/null +++ b/.changeset/edit-path-comment-checks.md @@ -0,0 +1,5 @@ +--- +'@systemfsoftware/claude-code-comment-checker': patch +--- + +Comments introduced by an `Edit` or `MultiEdit` are now judged the same way as comments written by a `Write`. Previously an edit reported only what a comment's own wording revealed — a bare `TODO`, commented-out code, a note about the change just made — so a comment that restated the code beside it or narrated the loop below it was reported on a whole-file write but passed on an edit. Nothing to configure; expect edits to existing files to be flagged more often.