Releasing buddi
Release flow v2: you ask for a release by pushing a release commit to main; CI tags it once the full gate is green, then publishes from the tag. Nobody pushes or moves a tag by hand.
What you type
Section titled “What you type”pnpm review # optional: the release review (README → Reviewing a release)pnpm release pre.44 --dry-runpnpm release pre.44 # or 0.1.0-pre.44pnpm release checks the tree is clean, on main and level with origin, that
v0.1.0-pre.44 does not exist and v0.1.0-pre.43 does, and that
CHANGELOG.md has Unreleased lines. Then it stamps new routes into
API_SINCE, moves the Unreleased lines under ## 0.1.0-pre.44 — <date>,
refreshes docs/api.md and docs/cli.md, writes release/REQUEST.json,
commits all of it as Release 0.1.0-pre.44, pushes main (no tag) and prints
the workflow run to watch. --dry-run reports the same and writes nothing.
If the push is refused (main moved), the commit is only local: git reset --hard <the commit it names>, pull, and run pnpm release pre.44 again.
What CI does
Section titled “What CI does”Two runs of .github/workflows/release.yml:
-
The push to main. The
planjob (scripts/release/plan.mjs) decides whether this push releases anything (the rule below). If not, the run ends with a notice. If so, it runs the full gate (gate.yml), and on green thetagjob tags the pushed commitv0.1.0-pre.44and starts run 2. -
The publish run, a workflow dispatch on the tag with
publish: true. It checks that the tag carries a request for that version and thatpackage.jsonagrees, then: publish to npm with provenance, the GitHub release (notes from the version’s CHANGELOG section), the withbuddi.com rebuild, the Chrome Web Store upload, thenmac-checkandmac-app(buddi.app, DMG, Sparkle feed).The store step sends the release’s
buddi-extension-<version>.zipwithscripts/release/cws-upload.mjs(the store API called directly, logging only the store’s own explanation, never the CLI’s output) and submits it for review. It runs only for a release npm tagslatest: once a stable version exists, pre-releases go out undernextand do not reach the store (send one by hand with the extension-store workflow). It needs three repository secrets minted once for the publisher account (chrome-webstore-upload-keys):CWS_CLIENT_ID,CWS_CLIENT_SECRET,CWS_REFRESH_TOKEN. Without them, or when the store refuses (a version still in review, a version that does not increase), the step leaves a notice and the release goes on; the zip stays on the GitHub release for a manual upload: Actions → extension-store → Run workflow with the version (.github/workflows/extension-store.ymlfetches that release’s zip and submits it). The manifest version is0.1.0.Nfor0.1.0-pre.N(packages/extension/scripts/version.mjs), so the first stable store build must be 0.1.1.
Publishing runs on the tag rather than in run 1 because npm’s provenance names
the ref the workflow ran for, and installers and buddi.app accept only
release.yml@refs/tags/v<version> (packages/install/src/provenance.ts).
A tag pushed with the workflow’s own token starts no workflow; a dispatch does.
ci.yml gates every push to main, its changelog check included. A push that
release.yml will tag is gated by both: twice on that one commit, so that
main’s own CI never skips a push.
The Node buddi.app ships
Section titled “The Node buddi.app ships”buddi.app carries one Node, pinned in apps/mac/NODE_VERSION, with npm beside
it, and an installed app runs every later buddi release on that Node: the
in-app updater installs new tarballs from npm, while a new Node arrives only
with a new app shell through Sparkle. So a buddi that needs a newer Node ships
a new DMG first: raise NODE_VERSION and bump apps/mac/SHELL_VERSION in a
release, let installed apps take that shell, and only then raise
engines.node. The runtime job of the push run
(scripts/release/runtime-gate.mjs) refuses to tag when any engines.node
(the root package.json, which the published manifest copies, or a package’s)
excludes the pinned version, or when the app’s recipe
(apps/mac/scripts/fetch-payload.sh) would ship node without npm; mac-app
then runs the signed app’s own runtime/node --version and
runtime/npm --version and checks them against the pin. The updater does not
yet check engines.node itself, so the order is what keeps an installed app
from updating to a buddi it cannot start.
The rule (plan.mjs)
Section titled “The rule (plan.mjs)”A push tags a release when all of these hold:
- The marker. The commit that last changed
release/REQUEST.jsonhas the subject exactlyRelease <version>, for the version the file names. Both are required: a commit message alone (anyone can type one) or a hand edit of the file starts nothing. A file changed by any other commit fails the run. - Recent. That commit is HEAD or one of its last 50 first-parent commits. Commits on top of it are fine: the tag goes on HEAD, so fixes pushed after the release commit are in the release.
- Untagged.
v<version>does not exist on origin. Once it does, every later push is “nothing to release”. - The right version. The version’s core is the root
package.json’s version (0.1.0for0.1.0-pre.N); otherwise the run fails.
release/REQUEST.json ({ "version", "from" }, from being the commit the
release was cut from, for the record) stays in the tree: each release commit
overwrites it, and a tagged version makes it inert. CI never writes to main.
Pushes to main queue in release.yml (one at a time; a newer push replaces
one still waiting), so two runs never race for the tag; the tag job also
refuses if the tag appeared on another commit while the gate ran.
A red gate
Section titled “A red gate”Nothing is tagged and nothing is published. Fix it and push to main: the next
push whose gate is green tags the release at that push’s commit, fix
included. A flaky failure needs no commit: re-run the failed jobs of that run,
and tag follows a green gate.
The same holds when the gate passed and only the publish dispatch at the end
of tag failed: re-run the failed jobs. tag finds the tag already naming
this commit, leaves it, and starts the publish run again; it fails only when
the tag names another commit.
Fixes pushed on top of the release commit should not add Unreleased lines for
this release: CHANGELOG.md already has its section. Edit that section if the
fix changes what it says.
A release whose gate never goes green stays requested: each push to main runs
the release gate as well as the ordinary one, until the release is tagged or
falls more than 50 commits behind HEAD. Then it is stale (a warning on each
push, never a tag). To release it after all, push a fresh commit with the
subject Release 0.1.0-pre.N that rewrites release/REQUEST.json with the
same version (pnpm release would refuse, since Unreleased is already empty).
Running parts again
Section titled “Running parts again”Actions → release → Run workflow:
- Mac app and Linux tarballs only (the npm release is out): use workflow
from the tag
v0.1.0-pre.44,version=0.1.0-pre.44,publishoff (gh workflow run release.yml --ref v0.1.0-pre.44 -f version=0.1.0-pre.44). Both jobs refuse any other ref, so what they attach is the tag’s code. - Publish again (the tag exists but the publish run failed, or was never
started): use workflow from the tag
v0.1.0-pre.44,version=0.1.0-pre.44,publishon. A version already on npm fails at the publish step; npm never takes a version twice.
