| name | release-catalyst |
| description | Cut a new release of Catalyst (`@bigcommerce/catalyst-core`, `@bigcommerce/catalyst-makeswift`, and `@bigcommerce/catalyst-b2b-makeswift`). Use when the user says "/release-catalyst", "cut a release", "release catalyst", or asks to publish new versions of the Catalyst packages. This skill orchestrates the full release process: merging the Version Packages PR on canary, syncing and releasing integrations/makeswift, then integrations/b2b-makeswift, and pushing @latest tags.
|
Release Catalyst
Execute stages in order. Pause for user input where indicated.
Stage 1: Cut release from canary
1a. Find and merge the Version Packages PR
gh pr list --search "Version Packages (canary)" --state open --json number,title,reviews,mergeable
- If no open PR exists, inform the user that there are no pending changesets on
canary and stop.
- If the PR is approved and checks are passing, merge it:
gh pr merge <number> --squash
- If the PR is not approved or checks are not passing, tell the user and wait.
1b. Verify the release
After the PR merges:
git fetch origin --tags
Determine the new @bigcommerce/catalyst-core version from the PR body (look for ## @bigcommerce/catalyst-core@X.Y.Z). Then verify:
gh release view @bigcommerce/catalyst-core@<version> --json tagName,name,isDraft,isPrerelease
If the release and tag don't exist yet, wait briefly and retry — the Changesets action may still be running.
Record the version number and bump type (patch/minor/major) for use in Stage 2.
Stage 2: Sync and release integrations/makeswift
2a. Sync branches
Invoke the /sync-integration-branch skill with target integrations/makeswift, with one addition: during the sync (after merge, before pushing), also add a changeset for @bigcommerce/catalyst-makeswift:
Determine bump type: Match the bump type from Stage 1 (e.g., if core went 1.4.2 → 1.5.0, that's a minor).
Create changeset file (.changeset/sync-canary-<version>.md, where <version> uses hyphens instead of dots — e.g., 1.6.0 → sync-canary-1-6-0.md). Changeset filenames only allow lowercase letters and hyphens; dots are invalid.
---
"@bigcommerce/catalyst-makeswift": <patch|minor|major>
---
Pulls in changes from the `@bigcommerce/catalyst-core@<version>` release. For more information about what was included in the `@bigcommerce/catalyst-core@<version>` release, see the [changelog entry](https://github.com/bigcommerce/catalyst/blob/<canary-sha>/core/CHANGELOG.md#<version-anchor>).
Where:
<canary-sha> is the merge commit SHA on canary (from the Version Packages merge)<version-anchor> is the version with dots removed (e.g., 1.5.0 → 150)
Include this changeset in the merge commit (amend if needed) alongside the normal sync work.
2b. Merge the Version Packages (integrations/makeswift) PR
After the sync lands, the Changesets action will open a "Version Packages (integrations/makeswift)" PR.
gh pr list --search "Version Packages (integrations/makeswift)" --state open --json number,title
Same flow as Stage 1a:
- If checks aren't running (bot PR), push an empty commit to trigger CI, then drop it before merging by resetting to the parent and force-pushing.
- Once approved and green, merge with
gh pr merge <number> --squash.
- Note: squash merging is normally disallowed on
integrations/makeswift to preserve merge bases for sync PRs. The user may need to temporarily enable squash merging in the branch protection rules for this step, then re-disable it after.
2c. Verify the makeswift release
git fetch origin --tags
gh release view @bigcommerce/catalyst-makeswift@<version> --json tagName,name,isDraft,isPrerelease
Stage 3: Sync and release integrations/b2b-makeswift
integrations/b2b-makeswift builds on integrations/makeswift, so it releases after Stage 2. If Stage 2 didn't cut a new makeswift release (no makeswift changes), skip this stage.
3a. Sync branches
Invoke the /sync-integration-branch skill with target integrations/b2b-makeswift, with one addition: during the sync (after merge, before pushing), also add a changeset for @bigcommerce/catalyst-b2b-makeswift:
Determine bump type: Match the bump type from Stage 2 (the makeswift bump).
Create changeset file (.changeset/sync-makeswift-<version>.md, where <version> uses hyphens instead of dots):
---
"@bigcommerce/catalyst-b2b-makeswift": <patch|minor|major>
---
Pulls in changes from the `@bigcommerce/catalyst-makeswift@<version>` release. For more information, see the [changelog entry](https://github.com/bigcommerce/catalyst/blob/<makeswift-sha>/core/CHANGELOG.md#<version-anchor>).
Where <version> is the makeswift version released in Stage 2, <makeswift-sha> is the Version Packages merge commit on integrations/makeswift, and <version-anchor> is that version with dots removed. The b2b package keeps its own version line: the bump type mirrors makeswift's, but the resulting @bigcommerce/catalyst-b2b-makeswift version number is independent of makeswift's.
Include this changeset in the merge commit (amend if needed) alongside the normal sync work.
3b. Merge the Version Packages (integrations/b2b-makeswift) PR
After the sync lands, the Changesets action opens a "Version Packages (integrations/b2b-makeswift)" PR.
gh pr list --search "Version Packages (integrations/b2b-makeswift)" --state open --json number,title
Same flow as Stage 2b:
- If checks aren't running (bot PR), push an empty commit to trigger CI, then drop it before merging by resetting to the parent and force-pushing.
- Once approved and green, merge with
gh pr merge <number> --squash.
- Same caveat as makeswift: squash merging is normally disallowed on
integrations/b2b-makeswift to preserve merge bases for sync PRs. Temporarily enable it for this step, then re-disable.
3c. Verify the b2b release
git fetch origin --tags
gh release view @bigcommerce/catalyst-b2b-makeswift@<version> --json tagName,name,isDraft,isPrerelease
Large catch-up: when reviving a branch that's many makeswift releases behind, run this stage once per makeswift minor tag (see the one-time catch-up in /sync-integration-branch), cutting a b2b release per rung so @latest marches forward cleanly.
Stage 4: Push @latest tags
Update the @latest tags to point to the new releases (skip any package that didn't get a new release this run):
git fetch origin --tags
git tag @bigcommerce/catalyst-core@latest @bigcommerce/catalyst-core@<core-version> -f
git tag @bigcommerce/catalyst-makeswift@latest @bigcommerce/catalyst-makeswift@<makeswift-version> -f
git tag @bigcommerce/catalyst-b2b-makeswift@latest @bigcommerce/catalyst-b2b-makeswift@<b2b-version> -f
git push origin @bigcommerce/catalyst-core@latest -f
git push origin @bigcommerce/catalyst-makeswift@latest -f
git push origin @bigcommerce/catalyst-b2b-makeswift@latest -f
Confirm the tags were pushed successfully.
Stage 5: Cleanup
git checkout canary
git pull
Delete any leftover local branches (changeset-release/*, sync-integrations-makeswift, integrations/makeswift, sync-integrations-b2b-makeswift, integrations/b2b-makeswift).
Report the final state: which package versions released, tags updated, branches cleaned up.
