scripts/changelog.mjs, the two ledgers, and the 0.1.0-0.1.5 backfill

cruelacid commented

2026-09-22 15:47:00 +01:00

Owner

Part of #77. Blocked by the merge-path proof (#78).

Why

There is no changelog anywhere, and docs/releasing.md:134 falsely claims
there is: "Every plugin release bumps manifest.json with a changelog line".
scripts/bump-plugin-version.mjs touches manifest.json, versions.json and
package.json and writes no changelog. Delete that claim as part of this.

What to build

docs/changelog-plugin.md and docs/changelog-server.md — the masters, in git.

Two ledgers rather than one is forced, not chosen. build-mirror.mjs's
FORBIDDEN scan rejects any staged file containing packages/server,
plan-phase or positioning.md, so a combined changelog could not be
published at all. Run that scan at cut so bad prose fails while it is being
written rather than during a release.

node scripts/changelog.mjs draft --product plugin --since v0.1.5
node scripts/changelog.mjs cut   --product plugin --version 0.1.6

draft reads merged PRs whose merge commit is an ancestor of HEAD and not of
v0.1.5, filters by area:* label, and takes release-notes/<PR>.md, else the
## Changelog block, else the PR title. Writes ## Unreleased, every line
carrying its PR number. Gate on the commit, never on a close or merge date —
those diverge from shipping in both directions with several sessions in flight.

It also reports orphans: commits in range reachable from no counted PR.
Branch protection should make that set empty, so a non-empty one means something
bypassed the workflow, which is worth knowing regardless.

Reading this needs no API. tea api 404s on everything here, including
tea api get user, but these work and return full bodies:

tea pulls ls  --state all    --fields index,title,body,labels --output json
tea issues ls --state closed --fields index,title,body,labels --output json

cut stamps the heading and drops the PR numbers. The draft is a file in the
worktree, edited like any other file — that is the review window, and it
needs no bespoke UI.

The LLM is a checker, not an author

draft --assist may propose prose for a thin note, as suggestions sitting
beside the sourced list. cut checks coverage. The documented risk is that an
LLM "can both omit changes and add ones that don't exist, both breaking the
changelog as a source of truth" — a checker cannot invent an entry, and a false
positive costs a glance.

Backfill 0.1.0-0.1.5

The material is in the release commits' own subjects, e.g.
79b78f9 Release 0.1.1: the first-run pane, and a name that cannot leave its folder.
Nothing invented: an entry nobody can trace to a commit does not go in.

Part of #77. Blocked by the merge-path proof (#78). ## Why There is no changelog anywhere, and `docs/releasing.md:134` **falsely claims there is**: "Every plugin release bumps `manifest.json` with a changelog line". `scripts/bump-plugin-version.mjs` touches `manifest.json`, `versions.json` and `package.json` and writes no changelog. Delete that claim as part of this. ## What to build `docs/changelog-plugin.md` and `docs/changelog-server.md` — the masters, in git. **Two ledgers rather than one is forced, not chosen.** `build-mirror.mjs`'s `FORBIDDEN` scan rejects any staged file containing `packages/server`, `plan-phase` or `positioning.md`, so a combined changelog **could not be published at all**. Run that scan at `cut` so bad prose fails while it is being written rather than during a release. ``` node scripts/changelog.mjs draft --product plugin --since v0.1.5 node scripts/changelog.mjs cut --product plugin --version 0.1.6 ``` `draft` reads merged PRs whose merge commit is an ancestor of `HEAD` and not of `v0.1.5`, filters by `area:*` label, and takes `release-notes/<PR>.md`, else the `## Changelog` block, else the PR title. Writes `## Unreleased`, every line carrying its PR number. **Gate on the commit, never on a close or merge date** — those diverge from shipping in both directions with several sessions in flight. It also reports **orphans**: commits in range reachable from no counted PR. Branch protection should make that set empty, so a non-empty one means something bypassed the workflow, which is worth knowing regardless. **Reading this needs no API.** `tea api` 404s on everything here, including `tea api get user`, but these work and return full bodies: ``` tea pulls ls --state all --fields index,title,body,labels --output json tea issues ls --state closed --fields index,title,body,labels --output json ``` `cut` stamps the heading and drops the PR numbers. The draft is a file in the worktree, edited like any other file — **that is the review window**, and it needs no bespoke UI. ## The LLM is a checker, not an author `draft --assist` may propose prose for a thin note, as suggestions sitting *beside* the sourced list. `cut` checks coverage. The documented risk is that an LLM "can both omit changes and add ones that don't exist, both breaking the changelog as a source of truth" — a checker cannot invent an entry, and a false positive costs a glance. ## Backfill 0.1.0-0.1.5 The material is in the release commits' own subjects, e.g. `79b78f9 Release 0.1.1: the first-run pane, and a name that cannot leave its folder`. **Nothing invented**: an entry nobody can trace to a commit does not go in.

cruelacid added this to the Backlog - unscheduled milestone

2026-09-22 15:47:00 +01:00

cruelacid added the

area:ops

label

2026-09-22 15:47:00 +01:00

cruelacid referenced this issue

2026-09-22 15:47:26 +01:00

Derive the GitHub release notes, and show them at the dry-run checkpoint #84

cruelacid referenced this issue

2026-09-22 15:47:26 +01:00

Derive /changelog onto nectenda.com #85