@thefittingroom/shop-ui 5.0.37 → 5.0.39

package/README.md

@@ -47,7 +47,7 @@ For an interactive debug loop, `npm run watch-serve &` in one terminal and
 Releases are explicit, human-initiated steps via a single GitHub Actions
 workflow. No magic on PR merges.
 
-**1. Cut a `next` release.**
+**1. Publish a release.**
 
 - Go to https://github.com/TheFittingRoom/shop-sdk-ui/actions/workflows/release.yaml
 - Click **Run workflow**
@@ -57,30 +57,47 @@ workflow. No magic on PR merges.
 The `release.yaml` workflow does everything in one run:
 
 1. Checks out `main`, installs deps, builds (verifies it compiles)
-2. Runs `npm version <bump>` — bumps `package.json` and creates the
-   `vX.Y.Z` tag
-3. Rebuilds with the new version embedded
-4. Pushes the bump commit + tag back to `main`
-5. Publishes to npm under dist-tag `next` via
+2. Creates a fresh `release-bump-<timestamp>` branch
+3. Runs `npm version <bump>` — bumps `package.json`, creates the
+   bump commit, tags it `vX.Y.Z`
+4. Rebuilds with the new version embedded
+5. Pushes the bump branch + tag (not to `main` — see below)
+6. Publishes to npm under dist-tag `next` via
    [npm trusted publishing](https://docs.npmjs.com/trusted-publishers)
    (OIDC, no long-lived secret) with `--provenance` for supply-chain
    attestation
+7. Opens a PR from the bump branch to `main` and queues auto-merge
 
 The npm trusted-publisher entry for `@thefittingroom/shop-ui` must
 point at `release.yaml`.
 
-> **Branch protection note:** the workflow pushes commits + tags
-> directly to `main`. If you enable required-PR branch protection on
-> `main` later, this push will fail until either (a) the workflow uses
-> a credential listed in the branch-protection bypass list, or (b)
-> branch protection allows the workflow to bypass via some other means.
-> The current setup deliberately defers that complication.
-
-**2. Promote `next` → `latest` when ready for end users.**
-
-`release.yaml` only publishes under dist-tag `next`. To make a version
-the default that consumers get from `npm install @thefittingroom/shop-ui`,
-you have to explicitly promote it:
+**Demo storefront visibility:** the `shopify` theme's `tfr.js` loads
+the SDK from `unpkg.com/@thefittingroom/shop-ui@5` — a semver range
+that unpkg (and jsdelivr) resolves to the highest matching published
+5.x version regardless of dist-tag. Publishing under `--tag next` is
+therefore enough for demo to pick up the new version on the next
+reload; no `latest` promotion is required for that path. Demo picks
+up the new version even before the auto-merge PR completes — npm
+publish and GitHub merge are independent steps.
+
+> **Ruleset + auto-merge note:** `main` is protected by a repository
+> ruleset requiring PRs + a passing `verify` check. `release.yaml`
+> works around this by pushing to a `release-bump-*` branch and
+> opening an auto-merge PR. The `verify` job in `pr-checks.yml` is
+> `if:`-skipped for `release-bump-*` branches (safe — the bump only
+> touches `package.json` + `package-lock.json` + a `dist/` rebuild
+> whose only diff is the embedded version), so the required-check
+> reports success immediately and auto-merge fires within seconds
+> of the branch push. See `AGENTS.md` → "Ruleset + auto-merge
+> coupling" for the full rationale.
+
+**2. (Optional) Promote to `latest` dist-tag.**
+
+Only matters for consumers who install without a version pin
+(`npm install @thefittingroom/shop-ui` → gets `latest`) or reference
+`@latest` in a CDN URL. The demo storefront does neither, so this
+step is not required for changes to appear on demo. When you do want
+to move the `latest` pointer:
 
 ```sh
 git pull origin main      # ensure package.json reflects the latest release