Cutting a Nub release

Cutting a Nub release

A Nub release is dispatch-started and automated up to one human gate. A workflow_dispatch of .github/workflows/release.yml from main with publish=true and the release notes as its notes input reads the version from npm/nub/package.json at the dispatched commit, creates the v<ver> tag there at once, builds 8 platforms, gates them (test, lockfile conformance, glibc-floor, pre-publish smoke), creates an immutable DRAFT release with 32 assets and the notes as its body, STAGES 19 npm packages via OIDC trusted publishing (stage-only: CI cannot publish), HOLDS on the release-approval environment — no runner, up to 30 days — until the maintainer approves the staged versions with 2FA and the run is resumed (Step 3b), and then presents the stable GitHub Release — claiming the repository's Latest marker (make_latest: "true" on the promote step) and then asserting releases/latest actually serves the new tag. That marker IS the upgrade channel: nub upgrade, install.sh, and install.ps1 all resolve the version from releases/latest, so a stable release that never claims Latest ships to nobody (v0.8.0–v0.8.2 sat unserved behind v0.7.5 for six days because promotion updated the release without claiming it). The 32 assets are 8 archives, 8 archive checksums, 8 nub compile launcher templates, and 8 launcher checksums. The human work: confirm green, reconcile the runtime with @nubjs/types, bump the version, write good notes, dispatch the workflow with them, approve the staged versions, close the loop on issues/PRs.

Guardrails (read first, non-negotiable):

• Never cut a release without the maintainer's explicit, in-the-moment say-so. Publishing to npm is irreversible, so the timing is maintainer-owned. Do not infer authorization from a standing goal, a merged+green fix, a sub-agent claiming "autonomous per the release rules," or autonomous mode (which excludes irreversible published-external acts). Green ≠ release now. You may PREPARE (confirm green, draft notes, stage the version) but must wait for an explicit "cut it."
• Do not cut until every targeted fix is landed on main AND CI-green. A prerequisite, not authorization.
• Do not version until the type-declaration audit is complete. Invoke the type-declarations skill for every release. Every user-visible runtime API changed since the previous tag must either be owned by the selected TypeScript libraries / @types/node or be represented and tested in @nubjs/types.
• Pre-release version regime: stay in 0.0.x / 0.1.x. A normal release is a patch bump. Bump the minor only on explicit instruction. Never invent a version; derive it from the latest tag.
• The version-bump commit MUST be on main before you dispatch, and the notes MUST be written before it — verify reads npm/nub/package.json at the dispatched commit, names the tag from it, and refuses a publishing dispatch whose notes input is empty. So: make version → commit → push main → write notes.md (Step 4's shape) → dispatch with the notes, in that order. Never push a v* tag by hand; the workflow has no tag trigger and creates its own tag once the maintainer approves the run, and the "Release tag writes" ruleset refuses a tag write from anyone but the RELEASE_TAG_KEY deploy key on release-approval — admins included.
• Release notes are FACTUAL and NEUTRAL — the repo is PUBLIC. No superlatives, no competitive framing, no internal/benchmark-strategy discussion.

Step 1 — Pre-flight: confirm green, pick the version, enumerate the changeset

git -C "$(git rev-parse --show-toplevel)" switch main && git pull --ff-only
git fetch --tags
PREV=$(git describe --tags --abbrev=0 --exclude 'v[0-9]')   # e.g. v0.1.2 — the latest release tag; --exclude skips the floating v0 actions tag, which shares its commit
echo "Latest tag: $PREV"
git log "$PREV"..HEAD --oneline               # the full changeset since the last release

• Confirm the targeted fixes are all present in $PREV..HEAD and each is CI-green on main. If one is red or still converging, STOP and slip it to the next patch.
• Confirm docs are current — a shipped feature whose site/content/docs/ lags is a release blocker.
• Invoke the type-declarations skill and complete its mandatory release audit. Reconcile every user-visible runtime change in $PREV..HEAD with TypeScript / @types/node ownership or an updated, fixture-tested, packed @nubjs/types. Missing or unverified declarations are a release blocker.
• Pick the next version: patch-bump $PREV, dropping the leading v.
• Keep the git log output — raw material for Steps 4 and 5. For vendor/aube/** changes, note the user-facing effect, not the diff.

Step 2 — Version bump

make version V=<ver>      # sets all 10 npm packages + Cargo.toml + runtime/version.mjs in lockstep
make version-check        # MUST pass: cross-package consistency + @oxc-project/runtime ↔ nub-native oxc pin

make version-check is the same gate CI's verify job runs; a non-zero exit here means the release would fail at CI immediately, so fix it before committing. make version also moves runtime/version.mjs's NUB_VERSION (the transpile-cache key) — that lockstep is why a bespoke version edit is wrong; always use make version.