docs(release): describe the release as it is now, and stop the plugin list rotting

[jouwdan]

docs/contributing/release.md was written when there were fifty packages, two first-party plugins and six marketplace listings. There are fifty-two, four and eight. Fixing the numbers alone would have left the same page to rot again at the next plugin, so this also removes the reason it rots — and, checking the document's claims against the code, turned up a live drift the release tooling was supposed to prevent.

The bug the doc found

release-check.mjs named its plugin manifests in a hardcoded list of two, written when there were two. Calendar and Webhooks were added after it, so nothing checked their definePlugin versions:

plugins/calendar/src/definition.tsx   version: '0.22.0'
plugins/webhooks/src/definition.tsx   version: '0.22.0'

Both shipped in v0.23.0, and pnpm release:check reported coherence throughout, because it never looked at them. /admin/plugins on a 0.23.0 board shows two plugins a release behind — the one place these constants are ever seen by an operator, and the exact failure the check exists to catch. The document already recorded this happening once before ("the plugin version once sat at 0.1.0 through two releases"); this is the second time, by a different route.

Both scripts now discover plugin manifests by walking plugins/, the way they already discover marketplace/listings/ — which is why the listings stayed correct when Calendar and Webhooks added theirs, and the plugin versions did not. A plugin whose definePlugin version cannot be read is an error rather than a silent omission, so a new plugin needs no edit to either script. release-bump gets the same treatment, so a bump moves all four rather than two.

The two stale versions are corrected to the release they shipped in. release:check goes from 2 plugin manifests to 4.

This does not fix the published v0.23.0, where those two manifests still say 0.22.0. That is cosmetic and confined to what /admin/plugins displays — worth a line in the release notes, or a 0.23.1, whichever you prefer.

What changed in the document

• The procedure moved to the top. A maintainer opening this page is almost always cutting a release; four numbered steps and the by-hand equivalent now come first, followed by what the pipeline does. The one-time setup — the deploy key, the first release, a package's first publish — is collected at the bottom, where it is looked up rather than read past.
• "Where the version is written" is a table, split by what keeps each entry honest: textually by release:check, or by a generator's own --check. Writing it out that way turned up templates/vercel, a generated artifact that stamps the version and was missing from the document entirely.
• The npm inventory states the rule instead of listing the packages. It was thirty-eight package names in one table cell, which is precisely what goes stale. It now says what is actually true — everything not private: true — keeps the categories, which carry meaning, and points at release:check's own closing count as the number to trust. The count is quoted once, as sample output, rather than asserted in prose in three places.
• Two arguments for lockstep versioning were made in separate sections; they are now one.
• Counts corrected throughout: fifty → fifty-two packages, two → four plugins, six → eight first-party listings.

Net 23 lines shorter, with the reasoning kept — the sections on determinism, trusted publishing, the closed set and shipping TypeScript source are unchanged in substance.

Validated

• pnpm release:check — 4 plugin manifests, 8 listings, 52 packages, coherent at 0.23.0.
• pnpm release:bump 0.23.1 run for real against a throwaway version: it rewrote all four plugin definitions and all four plugin manifests, regenerated every stamped document, and release:check agreed at the bumped version. Reset afterwards; the tree is back at 0.23.0.
• pnpm docs:links:check — every internal link and anchor resolves, including the two anchors other pages depend on (#the-version-policy from the upgrading guide, #one-version-everywhere from the marketplace page), both deliberately preserved.
• pnpm lint, pnpm comments:check, docs:index:check, site:docs:check, api:docs:check, marketplace:gen:check, board-installer:gen:check, vercel-template:gen:check, workspace:check, root:check, i18n:check — all pass.

No version moved.

🤖 Generated with Claude Code

https://claude.ai/code/session_016zJzrmeiQvSnyuQbEThdwv

---

Generated by Claude Code