Skip to content

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.

Terminal window
pnpm review # optional: the release review (README → Reviewing a release)
pnpm release pre.44 --dry-run
pnpm release pre.44 # or 0.1.0-pre.44

pnpm 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.

Two runs of .github/workflows/release.yml:

  1. The push to main. The plan job (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 the tag job tags the pushed commit v0.1.0-pre.44 and starts run 2.

  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 that package.json agrees, 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, then mac-check and mac-app (buddi.app, DMG, Sparkle feed).

    The store step sends the release’s buddi-extension-<version>.zip with scripts/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 tags latest: once a stable version exists, pre-releases go out under next and 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.yml fetches that release’s zip and submits it). The manifest version is 0.1.0.N for 0.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.

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.

A push tags a release when all of these hold:

  • The marker. The commit that last changed release/REQUEST.json has the subject exactly Release <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.0 for 0.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.

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).

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, publish off (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, publish on. A version already on npm fails at the publish step; npm never takes a version twice.