chore: migrate to changesets release PR workflow

Replace the direct-publish npm release workflow with the two-mode
changesets/action pattern: pending changesets create a release PR
titled "[ci] release"; merging it triggers npm publish.

Why: the previous workflow published to npm immediately on PR merge
with no human review gate for version bumps or changelogs. The release
PR pattern creates an intermediate PR showing exactly what will be
published before it goes out.

Key changes:
- Rewrite npm-release.yml to use changesets/action v1.7.0
- Switch trigger to push-to-main with queue concurrency
- Use SHOPIFY_GH_ACCESS_TOKEN (GITHUB_TOKEN can't re-trigger workflows)
- Add full git history fetch and registry-url for npm auth
- Enable @changesets/changelog-github for automatic changelog generation
- Add @changesets/changelog-github devDependency
- Set .changeset/config.json access to "public"
- Delete DEPLOYING.md (content moved to CONTRIBUTING.md)
- Add deploy/release/rollback docs to CONTRIBUTING.md
- Update CLAUDE.md and AGENTS.md symlinks to point to CONTRIBUTING.md
- Fix CHANGELOG.md v3.0.6 date from "(Unreleased)" to 2025-08-25
- Remove manual changeset detection and [ROLLBACK]/[DOCS] skip logic

Co-Authored-By: Claude <noreply@anthropic.com>

Author: kdaviduik

.changeset/config.json

@@ -4,7 +4,7 @@
   "commit": false,
   "fixed": [],
   "linked": [],
-  "access": "restricted",
+  "access": "public",
   "baseBranch": "main",
   "updateInternalDependencies": "patch",
   "ignore": []

.github/workflows/npm-release.yml

@@ -1,29 +1,31 @@
-name: Release new NPM version
+name: Release
 
 on:
-  pull_request:
-    types: [closed]
+  push:
     branches:
       - main
 
 concurrency:
-  group: changeset-${{ github.head_ref }}
-  cancel-in-progress: true
+  group: release-${{ github.ref_name }}
+  # IMPORTANT: Do NOT set cancel-in-progress to true.
+  # Cancelling an in-progress run could kill a mid-flight npm publish,
+  # leaving the repo in a half-published state. Queuing is safe — a second
+  # run after a publish is a harmless no-op (no changesets to consume).
 
 jobs:
-  npm:
-    name: Changeset release
+  release:
+    name: Release
     runs-on: ubuntu-latest
-    if: github.event.pull_request.merged == true && !contains(github.event.pull_request.title, '[ROLLBACK]') && !contains(github.event.pull_request.title, '[DOCS]')
+    if: github.repository_owner == 'Shopify'
     permissions:
-      contents: write # to be able to publish a GitHub release
-      pull-requests: write # to be able to comment on released pull requests
-      id-token: write # to enable use of OIDC for npm provenance
+      contents: write      # push version commits, create GitHub releases
+      pull-requests: write # create/update the "[ci] release" PR
+      id-token: write      # OIDC for npm provenance attestation
     steps:
-      - name: Checkout the repo
+      - name: Checkout
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
         with:
-          fetch-depth: 1
+          fetch-depth: 0
 
       - name: Setup pnpm
         uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4
@@ -33,44 +35,27 @@ jobs:
         with:
           node-version: "18.20"
           cache: 'pnpm'
+          registry-url: 'https://registry.npmjs.org'
 
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
-      - name: Check for changesets
-        id: check_changesets
-        run: |
-          if ! ls .changeset/*.md 1>/dev/null 2>&1; then
-            echo "No changesets found. Exiting."
-            echo "changesets_found=false" >> $GITHUB_ENV
-            exit 0
-          else
-            echo "changesets_found=true" >> $GITHUB_ENV
-          fi
-
-      - name: Update package version and remove changesets
-        if: env.changesets_found == 'true'
-        run: pnpm exec changeset version
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Publish to NPM
-        if: env.changesets_found == 'true'
+      - name: Create Release Pull Request or Publish
         id: changesets
-        uses: changesets/action@e0538e686673de0265c8a3e2904b8c76beaa43fd # v1.5.2
+        uses: changesets/action@6a0a831ff30acef54f2c6aa1cbbc1096b066edaf # v1.7.0
         with:
+          version: pnpm exec changeset version
           publish: pnpm exec changeset publish
+          commit: '[ci] release'
+          title: '[ci] release'
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # A PAT (not the built-in GITHUB_TOKEN) is required here. GitHub
+          # Actions blocks events from GITHUB_TOKEN from triggering workflows,
+          # so merging the release PR would not re-trigger this workflow for
+          # the publish step. SHOPIFY_GH_ACCESS_TOKEN is a GitHub App token
+          # scoped to this repo only (contents:write, pull-requests:write),
+          # rotated every 2 hours via github-actions-access-provider.
+          GITHUB_TOKEN: ${{ secrets.SHOPIFY_GH_ACCESS_TOKEN }}
           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
           NPM_CONFIG_PROVENANCE: true
-
-      - name: Update package.json version and reset changesets
-        if: env.changesets_found == 'true'
-        run: |
-          git config --global user.name 'github-actions[bot]'
-          git config --global user.email 'github-actions[bot]@users.noreply.github.com'
-          git add package.json .changeset CHANGELOG.md
-          git commit -m "Update package version & delete changesets"
-          git push

AGENTS.md

@@ -0,0 +1 @@
+CONTRIBUTING.md

CLAUDE.md

@@ -0,0 +1 @@
+CONTRIBUTING.md

CONTRIBUTING.md

@@ -1,8 +1,65 @@
 # How to contribute
+
 We ❤️ pull requests. If you'd like to fix a bug, contribute a feature or
 just correct a typo, please feel free to do so, as long as you follow
 our [Code of Conduct](https://github.com/Shopify/js-buy-sdk/blob/main/CODE_OF_CONDUCT.md).
 
 If you're thinking of adding a big new feature, consider opening an
 issue first to discuss it to ensure it aligns to the direction of the
 project (and potentially save yourself some time!).
+
+## Deploying and publishing
+
+### Publishing a new version
+
+1. Pull from main and install dependencies:
+   ```
+   git pull origin main
+   pnpm install
+   ```
+2. Create a changeset describing your changes:
+   ```
+   pnpm exec changeset add
+   ```
+3. Commit the changeset file alongside your code changes. **Do NOT manually update `CHANGELOG.md`** — it is generated automatically from changesets.
+4. Push and create a PR. **Do NOT bump the version in `package.json`** — changesets manages this.
+5. Merge the PR into `main`. The release workflow will automatically create a release PR titled `[ci] release`.
+6. Review the release PR — verify the version bump and `CHANGELOG.md` are correct.
+7. Merge the release PR. The release workflow will automatically publish the new version to npm and create a GitHub release.
+8. Deploy via [Shipit](https://shipit.shopify.io/shopify/buy-button-js/production) to publish the new version to Shopify's CDN. Press "Deploy", read and tick off the checkbox, then create and monitor the deploy.
+
+### Non-release changes
+
+If your PR doesn't need a new npm release (docs-only changes, test updates, CI changes, etc.), just don't include a changeset. No changeset = no release PR = no npm publish.
+
+### Rollback (update `latest` CDN version)
+
+Follow these steps to roll back the `latest` CDN version without publishing a normal npm release.
+
+1. Create a branch from `main` and revert the faulty code changes
+2. Do **not** include a changeset file. Verify no stale `.changeset/*.md` files exist (other than `README.md`):
+   ```
+   ls .changeset/*.md
+   ```
+   If any exist, delete them — stale changesets would cause the release workflow to open a release PR instead of a clean rollback.
+3. Append `-ROLLBACK` to the version in `package.json` (e.g., `3.0.6` → `3.0.6-ROLLBACK`)
+4. Run `pnpm install` to update the lockfile
+5. Stage and commit your changes
+6. Create a tag matching the new version:
+   ```
+   git tag 3.0.6-ROLLBACK
+   ```
+7. Push the branch and tags:
+   ```
+   git push && git push --tags
+   ```
+8. Create and merge the PR
+9. Deploy via [Shipit](https://shipit.shopify.io/shopify/buy-button-js/production)
+10. Purge the CDN cache via [Infra Central](https://infra-central.shopify.io/edge/purges):
+    - Press "New Purge" → choose "Url" → paste `https://sdks.shopifycdn.com/buy-button/latest/buybutton.js` → press "Create purge"
+
+> [!CAUTION]
+> The `-ROLLBACK` prerelease version will be published to npm. This is harmless — prerelease versions don't affect the `latest` dist-tag. **Never manually promote a prerelease to `latest`** via `npm dist-tag`.
+
+> [!CAUTION]
+> After a rollback, the next `changeset version` bumps from the rollback version normally. For example, `3.0.6-ROLLBACK` + a `patch` changeset → `3.0.7`. Verify the release PR shows the expected version before merging.

DEPLOYING.md

@@ -206,7 +206,7 @@ Use Graphite (gt) commands for managing stacked branches:
 
   - [ ] 3.4. Update `.github/workflows/ci.yml`: replace `npm install`/`npm run`/`npm test` with pnpm equivalents. Add pnpm setup step.
 
-  - [ ] 3.5. Update `.github/workflows/npm-release.yml`: replace `yarn install` with `pnpm install`, `npx changeset` with `pnpx changeset`. Add pnpm setup step.
+  - [x] 3.5. ~~Update `.github/workflows/npm-release.yml`~~ — Superseded: npm-release.yml was rewritten for the changesets release PR pattern.
 
   - [ ] 3.6. Update `.github/workflows/snapit.yml`: same pattern — replace yarn/npm with pnpm equivalents. Add pnpm setup step.
 
@@ -267,7 +267,7 @@ Use Graphite (gt) commands for managing stacked branches:
 
   - [ ] 4.7. Remove UglifyJS from dependencies: `uglify-js`
 
-  - [ ] 4.8. Update `CHANGELOG.md` documenting the breaking change (IE 11 drop)
+  - [ ] 4.8. Create a changeset via `pnpm exec changeset add` documenting the breaking change (IE 11 drop). CHANGELOG.md is now generated automatically — do not edit it manually.
 
   - [ ] 4.9. Verify: `pnpm test` passes, `pnpm run build` produces correct output, `pnpm run type-check` passes