refactor(changelog): tier releases by significance, publish routine ones automatically

[SPIKESPIGEL404]

Why

The changelog had stalled. The sync opened a PR asking a human to hand-write an entry for every release, so nobody merged it: #25 sat open for five weeks, the public page fell seven weeks behind, and 18 live entries still carried their "curate this, then merge" banner above raw git-cliff bullets. The curation gate was a bottleneck, not a quality filter.

The spine

significance: highlight | notable | routine — derived from the version shape, written into the frontmatter, overridable by hand. The page, the nav dot, RSS and the announcer all read the same field, so they can't disagree about what a release is worth.

Entering a new prerelease phase (beta.1, rc.1) counts as notable while later bumps stay routine — so an upcoming beta distinguishes itself with nothing to tag by hand.

Ordering

Sort by date → semver → url. Date alone was not a total order: alpha.18 and alpha.19 shipped the same day, so the tie fell back to filename order and alpha.18 wore the "latest" badge. Numeric prerelease segments now compare numerically (.9 before .10).

Page

Release notes render inline — no click-through to read what shipped. Runs of routine releases group under one collapsible header; a phase opening or a real release gets the display serif and stands out against them.

Rows are no longer Link wrappers: notes contain PR links and anchors can't nest, so the version in the rail carries the permalink. Per-release pages stay as permalinks for sharing, RSS and search.

Automation

• Routine-only syncs build-verify and push straight to main; anything notable opens a PR. (main isn't protected and create-pull-request PRs don't fire on: pull_request CI, so "auto-merge with required checks" was never actually available — the build in that job is the gate.)
• New scripts/check-changelog.mjs in CI: fails on an un-curated notable entry, a bad date, a duplicate version, or an entry below CHANGELOG_MIN_VERSION.
• The nav dot tracks the newest non-routine entry instead of pinging for every alpha bump.

Announcing

Channels follow significance: routine → Discord, notable → +X, highlight → +email.

Inert until deliberately enabled — ANNOUNCE_ENABLED must be true and the announce environment takes required reviewers. Email is only ever drafted in Resend, never sent. It's a workflow_call reusable workflow invoked by the sync, because a GITHUB_TOKEN push doesn't fire workflows and a push: trigger alone would have silently never announced a routine release.

Supersedes #29; see the closing comment there for where each of its ideas landed.

Generator bugs found while verifying

• ${VAR} broke the build. alpha.20's notes contain Don't expand ${VAR} inside YAML comments, which MDX compiles as a JS expression — ReferenceError: VAR is not defined, whole build dead. Release notes are arbitrary commit text, so they're now escaped (lib/mdx-escape.mjs).
• [**breaking**] was dropped and leaked. git-cliff's inline marker was neither detected as breaking nor stripped from the description, so the flag was lost and the raw markup rendered in the headline. Affected alpha.5, alpha.7, alpha.8.

Content

The public changelog now starts at the 1.0 alpha train: the five v0.x entries are gone and alpha.20–alpha.27 are recovered, closing the seven-week gap. CHANGELOG_MIN_VERSION floors both the sync and the check — the 49 v0.x releases still exist upstream, so a wide backfill would otherwise resurrect them (verified: a 100-release backfill writes 0 entries).

Companion PR: bitrouter/bitrouter#819 does the same cut to the Rust repo's CHANGELOG.md.

Verified

pnpm build passes, 126 tests pass, pnpm lint:changelog clean. Feed checked in the browser: 25 releases render notes inline, 3 breaking badges, 0 nested anchors, collapse works and returns the latest badge to the group header.

Before merging, note

There are currently no notable entries at all — every remaining release is a routine alpha, so /changelog is one train and LATEST_CHANGELOG_DATE is "" (nav dot off). That resolves itself when a beta lands, or sooner by promoting a few alphas with significance: notable.

Merging adds 8 entries and trips the announce push: trigger — harmless, since ANNOUNCE_ENABLED won't be set and the 14-day age guard would skip them anyway.

🤖 Generated with Claude Code