releases-maintenance.md

Maintaining the release history

ObjectStack ships as a single version-locked train: every @objectstack/* package (and the bundled @objectstack/console frontend) is in the changesets fixed group, so one number describes the whole platform. That number is the @objectstack/spec major — the same value as PROTOCOL_VERSION.

Because the release history spans ~70 backend packages and a separately-developed frontend, it is maintained in three layers. Each layer has exactly one owner (generated or curated) — never a hand-maintained aggregate, which is what drifts.

write time:   backend PR      → .changeset/*.md
              objectui bump    → .changeset/console-*.md   (auto, see below)
                       │ pnpm changeset version  (release pipeline)
                       ▼
detail layer: packages/*/CHANGELOG.md          ← generated, never hand-edited
                       │ curate per major (backend + frontend)
                       ▼
platform layer: content/docs/releases/vN.mdx   ← the whole-platform big picture

1. Atomic layer — changesets (written at change time)

Every behaviour-changing PR adds a .changeset/*.md describing the change and its migration while the context is fresh. This is the only place humans write release history for the backend. pnpm changeset version fans these out into the per-package changelogs and computes the next platform version.

2. Detail layer — per-package CHANGELOG.md (generated)

Generated by changesets, with PR links. Never hand-edit these. They are the exhaustive, per-package record for integrators and npm.

The frontend is a package too

The Console UI is developed in the sibling objectui repo and bundled into @objectstack/console at a pinned commit recorded in .objectui-sha. A SHA bump alone used to leave no trace in the history. scripts/bump-objectui.sh now closes that gap: on every bump it emits a @objectstack/console changeset summarising the objectui OLD_SHA..NEW_SHA commit range (auto-typed minor if the range contains any feat, else patch). So frontend deltas flow through the same pipeline as the backend — they land in @objectstack/console's changelog and roll up into the platform version.

scripts/bump-objectui.sh              # bump to ../objectui HEAD, write the changeset, commit
scripts/bump-objectui.sh <sha>        # bump to an explicit commit
CONSOLE_BUMP=patch scripts/bump-objectui.sh   # force the bump type
scripts/bump-objectui.sh --no-changeset       # opt out (rarely)

3. Platform layer — content/docs/releases/vN.mdx (curated)

The curated, developer-facing "big picture", written for third parties building on ObjectStack. One page per major, leading with breaking changes + migration, then new capabilities, then notable fixes — and a Console (Studio) section covering the frontend changes bundled in that line. This is the layer the whole platform version maps to.

Cadence that scales with rapid iteration:

• Major (breaking): a hand-curated vN.mdx is mandatory — migration guidance can't be generated.
• Minor / patch: do not add a page each. Fold them into the current major's page under a "What's new in N.x" running section, or leave them to the generated per-package changelogs.

Sourcing the Console section for a release

Backend content comes from the spec/package changesets. Frontend content comes from objectui's history for the SHA range bundled in that release. Because .objectui-sha is version-controlled, scripts/objectui-range.mjs computes that range from any two framework revisions and prints the frontend changes objectui declared over it — grouped by declared level (breaking / features / fixes), with the largest touched areas — ready to paste into a Console section:

# frontend delta bundled between two framework revisions (needs ../objectui)
node scripts/objectui-range.mjs <old-rev> <new-rev>   # e.g. the two release commits
node scripts/objectui-range.mjs --from <sha> --to <sha> --json   # explicit SHAs / tooling
node scripts/objectui-range.mjs <old-rev> <new-rev> --all         # also name what ships nothing

What "a frontend change" means here (#4843). The list comes from the .changeset/*.md files objectui added over the range, via the same classifyRange() in scripts/objectui-changeset-digest.mjs that bump-objectui.sh uses to write the pin changeset (#4731) — one criterion, two consumers, so the platform release record and this page's Console section cannot disagree. A changeset with an empty frontmatter block is changesets' own "release-nothing" marker and is excluded; so is a commit that added no changeset. Both exclusions are counted out loud in the printed markdown, because the output is release-page body text and a reader cannot otherwise tell a filtered list from a complete one. Headings group by declared level; grouping is presentation and never a filter.

This replaced a feat|fix guess on commit subjects. On the real range 7d9734d5e321..785b8a5d432c that guess dropped 13 commits that actually released — 6 of them breaking refactor(...)! — and listed 5 that release nothing.

Without an objectui checkout it still prints the SHA range to inspect. The framework changesets also embed companion frontend notes inline ("Companion objectui PR ships…", renderer notes), which are enough to write an accurate Console section on their own.

Pin freshness — the gate on the release PR (#3340)

Everything above reads the range OLD_PIN..NEW_PIN. That is exact, and it is also the whole blind spot: anything objectui merged after the current pin is outside every range, so it reaches no changeset, no changelog and no release page — and a complete-looking release record is indistinguishable from a complete one. Cutting v16 that way lost four frontend changes, two of them minor features, while objectui main sat 4 commits and 21 pending changesets ahead of the pin.

scripts/check-objectui-pin-fresh.mjs (pnpm check:objectui-pin-fresh) closes it. It is red when the pin is not objectui main (or the --ref you name), and it lists the commits ahead plus the .changeset/*.md files that exist at main and not at the pin.

pnpm check:objectui-pin-fresh                          # enforcing
node scripts/check-objectui-pin-fresh.mjs --advisory   # report only
node scripts/check-objectui-pin-fresh.mjs --ref v17.0.0 --json

• Where it blocks: the changesets Version Packages / release PR, via .github/workflows/objectui-pin-freshness.yml. The job runs on every PR — so the context always reports and can be a branch-protection required check — but passes --advisory outside the release lane, because a pin lagging between bumps is the normal state of an ordinary code PR.
• It is not the Console Pin Gate. ci.yml's Console Pin Gate (#4290) proves the pinned SHA still builds; this one proves the pin is still current. Either can be green while the other is red; neither replaces the other.
• Network failure is never green. git ls-remote alone decides the verdict, so the GitHub API (which only itemizes an already-established lag) can be rate-limited or down without turning red into green — the degradation is printed, not swallowed. An unreachable remote is reported as unreadable and exits non-zero.
• Fix when it fires: scripts/bump-objectui.sh to move the pin (which writes the @objectstack/console changeset for the crossed range), then re-source the Console section with scripts/objectui-range.mjs.

Drift guard

scripts/check-release-notes.mjs (run in CI as pnpm check:release-notes) fails the build when a released spec major has no content/docs/releases/v<major>.mdx wired into that section's meta.json. This is what prevents the "docs stuck at v9 while the platform shipped v14" gap from recurring. Curated pages started at v9; v10/v11 were never backfilled and are the documented exceptions in the guard.

The older aggregate files

Root CHANGELOG.md and RELEASE_NOTES.md were hand-maintained platform aggregates and drifted. They are retained for their historical entries but are superseded by the three layers above — prefer the per-package changelogs (detail) and the release pages (narrative) for anything new.