@mparticle/web-sdk 3.30.0 → 3.32.0

package/README.md

@@ -162,13 +162,181 @@ only at its Step 3. Once a V3 release has run on
 `staging-step-1.yml`. V2 runs the copies on `staging` and `master`, which this
 split does not change.
 
+The last V3 release cut by semantic-release, whose Step 3 brings `main` level
+with `v3-development`, ends that path. Every later V3 release is cut from
+`main` by Release Please, as the next section describes, and `v3-development`
+is retired.
+
+### V3 releases from `main` with Release Please
+
+V3 pull requests merge to `main`. Release Please reads their Conventional
+Commit titles and cuts each V3 release from `main`:
+
+1. **V3 Release Please** (`v3-release-please.yml`) keeps one release pull
+   request open on `main`. It carries the next version, the changelog entry and
+   the version of every kit.
+2. On each push to that pull request, **V3 Release Please - Commit Release
+   Bundles** builds core and every kit at that version and commits `dist/` and
+   `kits/**/dist` as the release machine user. The check **V3 release bundles
+   match version** passes once the committed bundles match that build. No other
+   pull request to `main` may change `dist/` or `kits/**/dist` (the check **V3
+   bundles change only in release PRs**).
+3. Before merging the release pull request, check that it does not show "This
+   branch is out-of-date with the base branch". If it does, wait for Release
+   Please to rewrite it and for **V3 release bundles match version** to go
+   green again. Hold other merges to `main` for a couple of minutes while you
+   merge. Release Please publishes the GitHub release and creates the `v3.X.Y`
+   tag on the merge commit.
+4. Run **V3 Release - Step 1** from that tag: in **Use workflow from**, choose
+   the tag, not a branch. Run it with `dryRun=true`, then `dryRun=false`. It
+   checks that the tag is on `main`, rebuilds core and every kit and compares
+   them with the tag's bundles, publishes core and every kit to npm `next`, and
+   then moves `v3-staging` forward to the tag commit. If a run stops part-way,
+   run Step 1 from the same tag again: it skips every package npm already holds
+   with the same bytes. A Step 1 run from a tag runs only while the
+   repository variable `V3_RELEASE_PLEASE_ENABLED` is `true`, and a run from
+   `v3-staging` fails once it is.
+5. Run Steps 2 and 3 from `main` as described below. Step 3 pushes only the
+   three release-order branches, because `main` already holds the release.
+   Don't change `V3_RELEASE_PLEASE_ENABLED` while a Step 3 run or its S3
+   promote is in progress. If a promote skipped because the variable changed,
+   run `promote-ga` by hand.
+
+`main` moves to the new version when the release pull request merges, and
+`ga` serves it only after `promote-ga`. In that window `main` is ahead of
+`ga` on every release. This is expected, and the gap closes at `promote-ga`.
+Roll a release back with **v3-shadow-promote**: `rollback` for one channel, or
+`rollback-all` for every channel in the selected pods. Rokt's internal V3 web
+SDK delivery runbook holds the serving checks for each release.
+
+Set the repository variable `V3_DIST_GUARD_ENABLED` to `true` once the first
+Release Please release pull request's bundle commit shows as **Verified** on
+GitHub. Until then, **V3 bundles change only in release PRs** passes with a
+note. Then add it and **V3 release bundles match version** to the required
+checks on `main`. When `V3_DIST_GUARD_ENABLED` is first set, or set again,
+re-run **V3 bundles change only in release PRs** on every open pull request to
+`main`. Each of them passed with a note while the variable was unset, and that
+result stands until the check runs again.
+
+#### Switch to Release Please
+
+1. Run the last V3 release cut by semantic-release with the three steps below,
+   Step 1 from `v3-staging`. Its Step 3 brings `main` level with
+   `v3-development`, and with it **V3 Release Please**, which does nothing
+   while `V3_RELEASE_PLEASE_ENABLED` is set to `false`.
+2. Lock `v3-development` with its ruleset, and retarget its open pull requests
+   to `main`. From here on, V3 pull requests merge to `main`.
+3. Before `V3_RELEASE_PLEASE_ENABLED` is set, merge one small pull request to
+   `main` that sets `.release-please-manifest.json` and `CHANGELOG.md` to that
+   release's version. The manifest reads that version. The changelog gains a
+   `# Changelog` title, and each semantic-release `# [3.X.0]` heading becomes
+   `## [3.X.0]`. Release Please adds each entry before the first `##` or `###`
+   version heading, so without this its first entry would land below that
+   release's.
+4. Set `V3_RELEASE_PLEASE_ENABLED` to `true`.
+5. Set `V3_DIST_GUARD_ENABLED` once the first release pull request's bundle
+   commit shows as **Verified**, as described above.
+
+#### When a release does not go as planned
+
+- **The release pull request merged, but no release or tag appeared.** Re-run
+  the failed **V3 Release Please** run. If it fails again, publish the release
+  from your own machine with the same files, then run Step 1 from the new tag.
+  The command pins release-please 17.6.0, the version that the workflow's
+  pinned `googleapis/release-please-action` v5.0.0 locks. Change both pins
+  together. For `GITHUB_TOKEN`, create a fine-grained personal access token
+  for this repository only, with a one-day expiry. Give it write access to
+  Contents, Pull requests and Issues, and nothing else (GitHub adds read-only
+  Metadata). Release Please labels the release pull request through the Issues
+  API. Delete the token once the release is published.
+
+  ```sh
+  npx release-please@17.6.0 github-release --token "$GITHUB_TOKEN" \
+    --repo-url mParticle/mparticle-web-sdk --target-branch main \
+    --config-file release-please-config.json \
+    --manifest-file .release-please-manifest.json
+  ```
+
+- **Abandon a release.** Before the merge, close the release pull request.
+  Release Please opens a new one on the next push to `main`, with every
+  unreleased change. To pause Release Please, set `V3_RELEASE_PLEASE_ENABLED`
+  to `false` first, then close the open release pull request. That pauses V3
+  releases. It does not bring back the semantic-release path (see **Fall back
+  to the semantic-release path**). Don't use the `autorelease: snooze` label.
+  With `always-update`, Release Please keeps force-updating a snoozed PR.
+  After the merge, if a release must not ship, do not run Step 1 for its tag.
+  Leave the tag and the GitHub release in place, never reuse the version, and
+  merge the fix to `main`. Release Please then cuts the next version, and Step
+  1 from that tag moves `v3-staging` past the abandoned one. This roll-forward
+  is how to replace a bad release.
+- **Release a chosen version.** Add the footer `Release-As: 3.X.Y` to the
+  commit message of a pull request merged to `main`, for example by editing
+  the squash commit message. The next release pull request then proposes
+  3.X.Y instead of the version the commit types give.
+
+#### Fall back to the semantic-release path
+
+Fall back only when Release Please itself cannot cut releases. To replace one
+bad release, roll forward as **Abandon a release** describes.
+
+Setting `V3_RELEASE_PLEASE_ENABLED` to `false` does not bring back the old
+path on its own. Step 1 from `v3-staging` builds whatever `v3-development`
+holds, and `v3-development` stops moving at the switch.
+
+It is safe to fall back only when no release is part-way. Every tag Release
+Please cut has finished Step 3 or was abandoned, and no Step 1, 2 or 3 run is
+in progress. Then:
+
+1. Set `V3_RELEASE_PLEASE_ENABLED` to `false` first, then close the open
+   release pull request without merging it.
+2. Unset `V3_DIST_GUARD_ENABLED`. Remove **V3 bundles change only in release
+   PRs** and **V3 release bundles match version** from the required checks on
+   `main`. The old Step 3 pushes each release to `main` directly, not through
+   a pull request.
+3. Lift the ruleset that locks `v3-development`. Then bring `v3-development`
+   and `v3-staging` up to `main`. If either ancestor check fails, stop: that
+   branch holds a commit `main` lacks. Merge it into `main` with a pull
+   request, then repeat this step. The push is not forced, so it only
+   fast-forwards.
+
+   ```sh
+   git fetch origin main v3-development v3-staging
+   git merge-base --is-ancestor origin/v3-development origin/main
+   git merge-base --is-ancestor origin/v3-staging origin/main
+   git push --atomic origin origin/main:refs/heads/v3-development \
+     origin/main:refs/heads/v3-staging
+   ```
+
+4. Point both Dependabot updates in `.github/dependabot.yml` back at
+   `v3-development`, and merge V3 pull requests there again. From here on,
+   only Step 3 moves `main`.
+5. Release with the three steps below, Step 1 from `v3-staging`. Step 1 and
+   semantic-release take the newest `v3.X.Y` tag reachable from `v3-staging`,
+   a Release Please tag included, so the next version follows it.
+
+Step 3 cannot push an older `v3-development` over a newer `main`. Without
+Release Please it pushes all five branches, `main` included. Before the push
+it checks that each one can fast-forward to the tag. If one cannot, it stops
+with `origin/main cannot fast-forward to v3.X.Y` and pushes nothing. That
+means a commit reached `main` outside Step 3. Merge `main` into
+`v3-development` with a pull request, then run Step 1 again.
+
+To return to Release Please, finish the last release's Step 3, so `main` and
+`v3-development` are the same commit. Then merge one pull request to `main`
+that sets `.release-please-manifest.json` and `CHANGELOG.md` to that release's
+version, as step 3 of **Switch to Release Please** describes, and points
+Dependabot back at `main`. Set `V3_RELEASE_PLEASE_ENABLED` to `true`, and merge
+V3 pull requests to `main` again. Set `V3_DIST_GUARD_ENABLED` again as
+described above.
+
 In GitHub Actions, choose the version's branch from the **Use workflow
 from** dropdown and run its workflows in order:
 
 1. **Step 1: Prepare CDN Pre-Release, Publish NPM**: run
    **Staging Release - Step 1** (`staging-step-1.yml`) from `staging` with
-   `track=v2`, or **V3 Release - Step 1** (`v3-release-step-1.yml`) from
-   `v3-staging`. This workflow builds and tests the version, creates and
+   `track=v2`, or **V3 Release - Step 1** (`v3-release-step-1.yml`) from the
+   V3 release tag (see the section above; before Release Please, from
+   `v3-staging`). From `staging` or `v3-staging`, this workflow builds and tests the version, creates and
    merges a generated release branch, runs semantic-release, and publishes the npm
    release. Before a new v3 release can advance, every existing kit `next` tag
    must match the core SDK's current `next` version. The one-time `3.0.0`
@@ -209,11 +377,15 @@ from** dropdown and run its workflows in order:
    the same rule as Step 2. For `releaseTag`, enter the same exact Git
    tag created by the successful Step 1 run. The workflow verifies that the tag
    matches `package.json`, resolves to the version's current staging head, and can
-   fast-forward every destination. It then uses one atomic push to synchronize
-   the version's development branch, trunk (`master` or `main`), and all three
-   release-order branches; either every ref updates or none does. `dryRun=true`
-   performs all validation without pushing. `dryRun=false` performs the atomic
-   synchronization and releases the candidate to those destinations.
+   fast-forward every destination. It then uses one atomic push, so either every
+   ref updates or none does. For v2, and for v3 before Release Please, that push
+   synchronizes the version's development branch, trunk (`master` or `main`),
+   and all three release-order branches. Once `V3_RELEASE_PLEASE_ENABLED` is
+   `true`, V3 Step 3 first checks that the tag is on `main`, then pushes only the
+   three release-order branches, because `main` already holds the release and
+   `v3-development` is retired. `dryRun=true` performs all validation without
+   pushing. `dryRun=false` performs the atomic push and releases the candidate
+   to those destinations.
 
 Safe sequence: run Step 1 with `dryRun=true`, then Step 1 with `dryRun=false`;
 copy its release tag; optionally preview and run Step 2 for each needed
@@ -299,7 +471,9 @@ A real v3 Step 1 run can publish core and create the GitHub Release before all
 2. Copy the exact release tag from the failed Step 1 run.
 3. Use the failed job and its npm kit publish summary to identify any
    missing or rejected kits. Correct their npm or trusted-publisher configuration.
-4. Dispatch **V3 Release - Step 1** from `v3-staging` with `dryRun=false`
+4. For a release Release Please cut, dispatch **V3 Release - Step 1** again
+   from the same tag with `dryRun=false`, and skip the rest of this step.
+   Otherwise, dispatch **V3 Release - Step 1** from `v3-staging` with `dryRun=false`
    and `resumeKitReleaseTag` set to the failed run's exact tag. If `main` has
    no `v3-release-step-1.yml` yet (the first V3 release after the split),
    dispatch **Staging Release - Step 1** from `v3-staging` with `track=v3`
@@ -341,7 +515,10 @@ from the branch selected in the **Use workflow from** dropdown, so every
 staging branch is identical to its trunk's copy: `staging-step-1.yml` on
 `staging` to `master`'s, and `v3-release-step-1.yml` on `v3-staging` to
 `main`'s. During the switch to the V3 files, a `track=v3` run of
-`staging-step-1.yml` from `v3-staging` must match `main`'s copy instead.
+`staging-step-1.yml` from `v3-staging` must match `main`'s copy instead. A V3
+Step 1 run from a release tag requires the tag's commit to be on `main`
+instead, so a later edit to the workflow on `main` does not block an earlier
+tag.
 
 npm trusted publishing names the workflow file that publishes each package:
 `staging-step-1.yml` publishes v2 of `@mparticle/web-sdk`, and