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

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