ci: let the release pull request merge itself on a cadence switch

Changesets keeps one release pull request open and rewrites it as changesets
land, so how often that pull request is merged is what decides the version
sequence. Left to accumulate it collapses a backlog into a single bump — which
is how nineteen changesets became one version and the numbers in between never
existed.

`AUTO_MERGE_RELEASE_PR` picks the cadence. Set to `true`, the release pull
request merges itself once its required checks pass, so one merge to main is
one release and the version tracks each change. Unset, nothing changes and a
maintainer merges it when a release is wanted.

This is not a blanket auto-merge: it only ever targets the changesets-authored
branch, the repository still requires its status checks, and a major bump is
gated on the pull request that introduces the changeset — so an unattended
release cannot rename the major version on its own. The step never fails the
run, because a version pull request left open costs a manual merge while a
failure here would block npm, the Marketplace and the CDN behind it.

CONTRIBUTING now states the bump levels and both cadences, so the version
sequence is a documented choice rather than a side effect of merge timing.

Author: elkaix

.github/workflows/release.yml

@@ -180,6 +180,39 @@ jobs:
           fi
           echo "Cut ${tag} at ${GITHUB_SHA} (desktop ${prev} -> ${curr})."
 
+      # Release cadence switch. With this on, the version PR merges itself once
+      # every required check passes, so one merge to main becomes one release
+      # and the version tracks each change instead of collapsing a backlog of
+      # changesets into a single jump. Turn it off to go back to releasing by
+      # hand: `gh variable set AUTO_MERGE_RELEASE_PR --body false`.
+      #
+      # This is deliberately not a blanket auto-merge. It only ever targets the
+      # changesets-authored branch, the repository requires its status checks
+      # before any merge, and a major bump is gated separately on the pull
+      # request that introduces the changeset — so an unattended release can
+      # still never rename the major version on its own.
+      #
+      # Never fail the release over this: a version PR that stays open costs a
+      # manual merge, while a failure here would block npm, the Marketplace and
+      # the CDN behind it.
+      - name: Enable auto-merge on the version PR
+        if: steps.changesets.outputs.published != 'true' && vars.AUTO_MERGE_RELEASE_PR == 'true'
+        continue-on-error: true
+        env:
+          GH_TOKEN: ${{ steps.release-bot.outputs.token }}
+        run: |
+          set -uo pipefail
+          pr=$(gh pr list --head changeset-release/main --state open --json number --jq '.[0].number' || true)
+          if [ -z "$pr" ] || [ "$pr" = "null" ]; then
+            echo "::notice::No open version PR; nothing to auto-merge."
+            exit 0
+          fi
+          if gh pr merge "$pr" --squash --auto; then
+            echo "Auto-merge armed on #${pr}; it lands when its required checks pass."
+          else
+            echo "::warning::Could not arm auto-merge on #${pr}. Merge it by hand to cut the release."
+          fi
+
       - name: Request CodeRabbit review on version PR
         if: steps.changesets.outputs.published != 'true'
         env:

CONTRIBUTING.md

@@ -80,6 +80,27 @@ This repo uses [changesets](https://github.com/changesets/changesets) to manage
 - Generate one with `pnpm changeset` and follow the prompts (which packages are touched, which bump level).
 - For repo-specific conventions on package selection and bump levels, see `.changeset/README.md`. When working in this repo with coding agents, use the `gen-changesets` skill.
 
+### Bump levels
+
+| Level | Use for | Example |
+| --- | --- | --- |
+| `patch` | A fix, or a small addition to something that already exists | `2.1.2` → `2.1.3` |
+| `minor` | A capability a user could not reach before | `2.1.3` → `2.2.0` |
+| `major` | A break: something that worked stops working, or works differently | `2.2.0` → `3.0.0` |
+
+Prefer one changeset per pull request. A pull request that needs several is usually several releases wearing one hat, and the changelog cannot attribute the changes afterwards.
+
+A `major` needs a maintainer's sign-off: the `changeset-policy` workflow fails a pull request that adds one unless it carries the `breaking-change-approved` label. A major renames the release and breaks every pinned install, and an npm publish cannot be taken back — so it is a decision, never a side effect of a large branch.
+
+### Release cadence
+
+Changesets keeps a `ci: release packages` pull request open on `main` and rewrites it as changesets land. Merging it cuts exactly one release, so how often it is merged is what decides the version sequence:
+
+- Merged per change, versions follow each change: `2.1.2`, `2.1.3`, `2.1.4`, `2.2.0`.
+- Left to accumulate, a backlog collapses into one bump and the numbers in between never exist.
+
+The repository variable `AUTO_MERGE_RELEASE_PR` chooses between the two. Set to `true`, the release pull request merges itself once its required checks pass, giving one release per change. Unset or `false`, a maintainer merges it when a release is wanted.
+
 ## Pull Requests
 
 Every PR opens with the [PR template](.github/pull_request_template.md). PR titles must follow [Conventional Commits](#commit-convention); CI runs `pnpm lint`, `pnpm typecheck`, and `pnpm test` on every PR. Update user-facing docs in `docs/` when behavior changes — use the `gen-docs` skill when working with coding agents.