Skip to content

releases-maintenance.md

Latest commit

 

History

History
101 lines (79 loc) · 5.01 KB

releases-maintenance.md

File metadata and controls

101 lines (79 loc) · 5.01 KB
Raw

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 feat/fix commits grouped by type + 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

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.

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.