* chore(release): author release notes in .changes instead of reconstructing them
CHANGELOG.md has been frozen at 0.12.0 since 2023 while the app shipped
0.23.0, semantic-release sat in devDependencies with no config, and the real
user-facing notes were a 280-line MDX post written from memory at release
time. The gap was never version math — it was authored notes captured while
the context is still fresh.
Add a `.changes/*.md` note format (type, area, issues, screenshot; no version
field, since the release version is chosen deliberately) plus a generator that
composes the GitHub release body, the CHANGELOG.md section and a blog-post
scaffold from the accumulated notes.
Changesets was considered and rejected: it versions multiple published
packages, and this repo has exactly one private package. Its `version` step
would also rewrite CHANGELOG.md into a flatter format than the blog post and
fight the deliberate, updater-constrained version choice.
- hand-rolled frontmatter parser over a YAML engine: the schema is closed, so
it can reject unknown keys, which is what catches typos
- PR numbers are resolved from the commit that added the note, never written
by the author
- MDX-significant characters in note bodies are escaped so a stray `<` cannot
break the website build
- blog scaffold ships `draft: true` with explicit TODO headings; the prose is
editorial work, only the inventory is mechanical
- revive CHANGELOG.md with an honest pointer for 0.13.0-0.23.0 rather than
fabricating the missing history
- drop the five unused semantic-release/conventional-changelog packages
Docs: `.changes/README.md`, plus a "Release Notes For User-Visible Changes"
section mirrored in CLAUDE.md and AGENTS.md, and a PR template checkbox for
contributors who never read either.
Tests: 26 unit tests in tools/release/release-notes.test.mjs covering parsing,
validation, grouping and all three renderers.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* fix(release): default the notes version to package.json and harden alt escaping
Review follow-ups on the release-notes generator.
- `--version` now defaults to the root package.json version, so the
`release🎶*` package scripts run bare instead of failing on a missing
argument. Bumping package.json is the deliberate act that starts a release,
which makes it the right single source of truth; `--version` remains as an
override for dry runs before the bump. The notice goes to stderr so
`--format github` keeps a pipeable stdout.
- Escape backslashes before apostrophes when building the MDX `alt` string
literal. A note body ending in a backslash previously produced an
unterminated string and would have broken the website build.
- Document that release posts are one per minor version, in the slug helper,
the overwrite error, and `.changes/README.md` — a patch release edits the
existing post rather than creating a second one.
Tests: +1 regression test for the alt escaping, verified to fail without the
fix (27 total, all passing).
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* feat(ci): put authored notes into the tag release body, fail-closed
Wires the .changes pipeline into the release workflow (Codex review P1 on
#1256). Calling the generator from the tag build cannot work — --consume
deletes .changes/ before the tag exists — so the tag build reads what the
generator already wrote: release-meta now fills BODY from the CHANGELOG.md
section matching the tag's version via tools/release/extract-changelog-section.mjs.
generate_release_notes stays on, so GitHub's commit list renders below the
authored notes; the existing draft-metadata repair step already concatenates
RELEASE_BODY with the generated notes, so the rare duplicate-draft path keeps
the same layering unchanged.
The extractor exits non-zero when the section is missing or empty, failing
the release instead of silently shipping PR-title-only notes. A hotfix tag
cut without running release:notes:changelog therefore fails at create-release
by design; the error message names the exact commands to run.
Tests: 5 new extractor tests (32 total in release-tools, all passing);
packaging suite (247) re-run green since build-and-make.yaml is one of its
inputs.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* fix(release): escape all regex metacharacters in the changelog extractor
CodeQL flagged the version-to-RegExp interpolation in
extract-changelog-section.mjs (regex injection + incomplete escaping): only
dots were escaped, and while the CLI validates its argument as bare semver
before calling, the exported extractSection() carries no such guarantee on
its own. Escape the full metacharacter set so no caller can inject pattern
syntax, with tests covering wildcard dots, alternation, `.*` and backslashes.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* fix(release): make changelog generation idempotent per version
Codex review P2 on #1256: rerunning `release:notes:changelog` for the same
version — the normal move after correcting a note before --consume —
prepended a second section instead of replacing the first, leaving duplicate
release entries.
Extract the marker insertion into upsertChangelogSection(): it removes any
existing section for the version, then rebuilds around the marker rather than
string-replacing into it, so the blank-line count on both sides stays exact
on both the fresh-insert and replace paths. The CLI reports when a section
was replaced.
Tests: 4 new cases (insert, replace-not-duplicate, neighbours untouched,
missing marker); 37 total passing. End-to-end rerun verified: one heading,
latest date wins, extractor output unchanged.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
4gray