From a0152a32eb83e235cad572d1586a9103a05b562f Mon Sep 17 00:00:00 2001 From: JohnnyT Date: Sat, 22 Aug 2026 00:33:10 -0600 Subject: [PATCH] Adopts changelog fragments Sets changelog.mode to fragments (dir changelog.d) in .claude/wurk.json and adds changelog.d/README.md, adapted from statifier-ex's: the why-fragments rationale, the when-a-fragment-is-warranted test, the format rules, and the at-release assembly step. The statifier-ex-only v2-rewrite and SHA-pinning clauses are deliberately not carried over. Un-ignores changelog.d/ in .gitignore, since a global *.d rule (C/C++ dependency files) would otherwise hide the fragments. Replaces the "Changelog: none" section of .claude/wurk/commit.md with the fragment step: the mode switch lands ahead of sui-n0r's at-first-release timing, per the fleet-wide adoption decision of 2026-08-21; 0.1.0's changelog section is still written in one pass at release. Refs: sui-6vy --- .claude/wurk.json | 3 +- .claude/wurk/commit.md | 32 ++++++++------- .gitignore | 4 ++ changelog.d/README.md | 93 ++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 117 insertions(+), 15 deletions(-) create mode 100644 changelog.d/README.md diff --git a/.claude/wurk.json b/.claude/wurk.json index 54483ca..bffe10b 100644 --- a/.claude/wurk.json +++ b/.claude/wurk.json @@ -78,7 +78,8 @@ }, "changelog": { - "mode": "none" + "mode": "fragments", + "dir": "changelog.d" }, "release": null diff --git a/.claude/wurk/commit.md b/.claude/wurk/commit.md index d3a6233..45fc846 100644 --- a/.claude/wurk/commit.md +++ b/.claude/wurk/commit.md @@ -3,20 +3,24 @@ Additional required steps. Adds only - see `~/.claude/skills/wurk:commit/SKILL.md` for everything this does not repeat. -## Changelog: none - -`changelog.mode` is `none` in the manifest, so there is no fragment step and -nothing to ask about. - -This is a decision, not an omission. While the package is `0.1.0-dev` with no -users and no public API, every entry would say some version of "the package -started existing" - and 0.1.0's changelog is better written in one pass from -git history than assembled from a pile of per-bead fragments, which is only -possible while there is no prior release to diff against. - -sui-n0r switches this to `fragments` when the first release is on the horizon, -and says why fragments rather than a single `CHANGELOG.md`. Do not start -writing changelog entries before then; do not let `none` outlive the release. +## Changelog: fragments + +`changelog.mode` is `fragments` with `changelog.dir` at `changelog.d` +(sui-6vy, adopted fleet-wide 2026-08-21 so the convention exists before +parallel work starts, not after the first conflict). A user-facing change +gets one file per bead under `changelog.d/`; the rules - when a fragment is +and is not warranted, format, naming - live in `changelog.d/README.md`. + +While the package is `0.1.0-dev` with no users and no public API, most +changes still warrant no fragment: apply the README test (could someone who +only ever calls the public API tell the difference?) and expect the answer +to usually be no. 0.1.0's own changelog section is still written in one +pass from git history at release time (sui-n0r), which is only possible +while there is no prior release to diff against; fragments cover what lands +after that pass makes sense. + +`CHANGELOG.md` itself does not exist yet and is never edited outside a +release. ## Version bump: none diff --git a/.gitignore b/.gitignore index 2c5bb4c..36e1b5d 100644 --- a/.gitignore +++ b/.gitignore @@ -22,6 +22,10 @@ statifier_ui-*.tar # Temporary files, for example, from tests. /tmp/ +# Changelog fragments are tracked. A global gitignore rule for `*.d` (C/C++ +# dependency files) matches this directory name and would otherwise hide them. +!changelog.d/ + # Beads / Dolt files (added by bd init) .dolt/ *.db diff --git a/changelog.d/README.md b/changelog.d/README.md new file mode 100644 index 0000000..4aaa545 --- /dev/null +++ b/changelog.d/README.md @@ -0,0 +1,93 @@ +# Changelog fragments + +Changelog entries for unreleased work live here as one file per issue, not as +edits to `CHANGELOG.md`. At release the fragments are assembled into a single +version section and deleted. + +## Why fragments + +Parallel work happens in one worktree per issue, so several branches are +usually open at once. If each branch appended to the `## [Unreleased]` block +at the top of `CHANGELOG.md`, every branch would touch the same few lines of +the same file and nearly every pull request would conflict with every other +one. + +A fragment is named after its issue, so no two branches ever write the same +file and the conflict cannot happen. + +## When a change needs a fragment + +The changelog serves **people who use the library**. Repo history is git's +job, and work tracking is beads' job. Neither belongs here. + +Write a fragment for: + +- a public API addition, change, or removal +- a change in observable behavior +- a change to a published contract - the fixtures layout or the trace wire + format - that a consumer could notice +- a bug fix a user could have noticed +- anything breaking + +Do **not** write a fragment for: + +- test harness or internal test-support changes +- documentation, ADRs, or plans +- internal refactors with no visible effect +- quality gate, CI, or agent tooling changes + +If you are unsure, ask whether someone who only ever calls the public API +could tell the difference. If not, skip it. + +## Format + +One file per issue, named for the beads issue ID: + + changelog.d/sui-abc.md + +Contents are the Keep a Changelog section heading followed by the entry: + +```markdown +### Changed + +- `StatifierUI.Trace.Json.decode/1` returns `{:ok, message}` instead of a + bare message. +``` + +Rules: + +- Use only the standard headings: `Added`, `Changed`, `Deprecated`, `Removed`, + `Fixed`, `Security`. +- One line per change, present tense, describing the effect on the user. +- No nested bullets. Detail belongs in the pull request and the commit body; a + changelog line that needs sub-points is really several changes or one that + is over-explained. +- One file may carry more than one heading if an issue genuinely spans them. +- For a breaking change, say what to do about it, not just what broke. + +Good: + +```markdown +### Removed + +- Drops `StatifierUI.Fixtures.validate/1`. Layout errors now arrive as + `{:error, reason}` from `StatifierUI.Fixtures.load/1`. +``` + +Too much: + +```markdown +### Removed + +- **Validator removal**: The validator function has been removed + - **Rationale**: Validation is now part of loading + - **Impact**: Callers must handle `{:error, reason}` + - **Migration**: Replace calls to ... +``` + +## At release + +Assemble the fragments into a new version section in `CHANGELOG.md`, grouped +by heading and ordered `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, +`Security`. Delete the fragments in the same commit that cuts the release, +and tag it.