docs(changelog): the unreleased section shortens to the house rule - #178
Merged
Conversation
The rule says a bullet is one line — the change, and at most one clause of reason — and that the whole unreleased section gets shortened before it is retitled for a release. It had drifted a long way from that: 47 bullets, 41 of them running past a single line, 120 lines total. Someone scanning for what changed was reading the reasoning behind it instead. Now 46 bullets, none longer than two wrapped lines, 95 lines. The reasoning did not disappear; it lives in the pull requests, which is where the rule says it belongs. Shortening surfaced a wrong fact, which is the better find. The kaish bullet said "upgraded to 0.17.1 (from 0.14.1)" while a separate Fixed bullet announced "Bump kaish-kernel to 0.14.1" — the same cumulative jump stated twice, from a baseline that was not the released one. v0.3.0 shipped on kaish-kernel **0.14.0** (checked with `git show v0.3.0:Cargo.toml`), so a reader upgrading from the last release was told the wrong starting point. It now reads "from 0.14.0", once, and 0.14.1's user-visible fix — the explorer's shell dropping piped stdin — stays in Fixed as the fix rather than as a version bump. Compression was checked for loss, not assumed: diffing the vocabulary of both versions turned up four things a user would act on that the first pass had dropped, and all four are back — that a slow generation returns a `job-N` handle, that base64 `content` is still the way in for an image that is not a file, the four image formats `write_cas` accepts by signature, and the twenty-fold cost spread across operations, since an exact number is the whole point of publishing one. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
tobert
added a commit
that referenced
this pull request
Sep 3, 2026
…release page (#180) **Release-blocking.** #175 measured the cosign floor and corrected `README.md`. It corrected *only* `README.md` — I grepped one file instead of the repo, on a change whose entire subject was a claim repeated across surfaces. That is the "an idiom is never in one file" lesson, and I did not apply it. Two instances survived: - **`.github/release-body.md:36` — this becomes the GitHub release page body.** `release.yml:235` runs it through `envsubst` into `body_path`, so it is the copy every person downloading v0.4.0 reads. It would have shipped with tomorrow's tag telling them to go install cosign 3 to verify a signature that 2.5 verifies. - **`docs/releases.md:62`** — the pipeline plan, asserting the same floor as fact. Both now say **2.5**, the measured floor: 2.4.0 cannot read the bundle format; 2.5.0, 2.6.0 and 2.6.4 verify a real release, with a tampered file and a wrong tag identity both refusing. ## How it was found — and why neither half alone would have A `consult` on the release branch, run as a live end-to-end exercise of the 0.17.1 shell before tagging. It found `docs/releases.md:62` and missed the release page. The repo-wide `grep` I ran to *verify its citation* found the release page — the one that actually mattered. So the review caught what my grep in #175 missed, and my grep caught what the review missed. Worth recording as an argument for doing both rather than either. ## Also here — same family, prose the recent changes left stale `docs/sandbox-probes.md:24` promised "paths outside the mount ... resolve to nothing" in the summary at the top of the runbook. 0.17.1's walkable prefix directories made that too broad. Battery C already carves out the exception a hundred lines down, so this is the headline catching up: it now says what it means (a *file read*) and points at C. ## Not taken from the same review It also reported `CHANGELOG.md:72`'s *"kaish upgraded to 0.17.1 (from 0.14.0)"* as stale against AGENTS.md's *"from 0.14.1"*, and recommended changing the changelog. **The changelog is right.** `git show v0.3.0:Cargo.toml` pins the last release at kaish-kernel **0.14.0**, and a changelog's baseline is the last release. AGENTS.md's 0.14.1 is the pre-bump *working* pin — a different, internal baseline. Changing it would have reintroduced exactly the error #178 fixed. Verified before declining, not assumed. Docs only — no code. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
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
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.
Pre-release item four. The house rule is that a changelog bullet is one line — the change,
and at most one clause of reason — and that the whole unreleased section gets shortened
before it is retitled for a release.
It had drifted a long way from that. Someone scanning for what changed was reading the
reasoning behind it instead:
The reasoning did not disappear — it lives in the pull requests, which is where the rule
says it belongs.
The better find
Shortening surfaced a wrong fact. The kaish bullet said "upgraded to 0.17.1 (from
0.14.1)" while a separate Fixed bullet announced "Bump
kaish-kernelto 0.14.1" —the same cumulative jump stated twice, from a baseline that was not the released one.
v0.3.0 shipped on kaish-kernel 0.14.0:
So a reader upgrading from the last release was told the wrong starting point. It now
reads "from 0.14.0", once — and 0.14.1's user-visible fix (the explorer's shell dropping
piped stdin) stays in Fixed as the fix it is, rather than as a second version bump.
This is the same class of error #174's review asked me to double-check on the "from"
baseline. That check confirmed 0.17.0 had never shipped; it did not look at whether
0.14.1 had. It hadn't.
Compression was checked for loss
A shortening pass that quietly drops a change is worse than a long changelog, so this was
verified rather than trusted: diffing the vocabulary of both versions turned up four
things a user would act on that the first pass had dropped. All four are back —
job-Nhandle rather than holding the call;contentis still the way in for an image that is not a file;write_casaccepts by signature (png, jpeg, gif, webp);of publishing one.
Everything else that fell out was reasoning, an implementation detail (
multipart,init_image/style_image,ultra/sd3), or a duplicate.Changelog only — no code.
🤖 Generated with Claude Code