feat: switch to changesets release PR workflow

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

docs/tasks/tasks-prd-typescript-migration.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