Skip to content

docs(changelog): the unreleased section shortens to the house rule - #178

Merged
tobert merged 1 commit into
mainfrom
docs/changelog-shorten
Sep 3, 2026
Merged

docs(changelog): the unreleased section shortens to the house rule#178
tobert merged 1 commit into
mainfrom
docs/changelog-shorten

Conversation

@tobert

@tobert tobert commented Sep 3, 2026

Copy link
Copy Markdown
Owner

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:

before after
bullets 47 46
running past one line 41 0
lines 120 95

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-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:

$ git show v0.3.0:Cargo.toml | grep kaish-kernel
kaish-kernel = { version = "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 —

  • a slow generation comes back as a job-N handle rather than holding the call;
  • base64 content is still the way in for an image that is not a file;
  • the four formats write_cas accepts by signature (png, jpeg, gif, webp);
  • the twenty-fold cost spread across operations — an exact number is the whole point
    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

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
tobert merged commit d54ef3a into main Sep 3, 2026
1 check passed
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)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant