@mparticle/web-sdk 3.29.1 → 3.31.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,25 +377,90 @@ 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
 release-order branch; finally run Step 3 with `dryRun=true`, then
 `dryRun=false`.
 
-Shadow v3 candidate packaging: when the `V3_PACKAGE_CANDIDATE` repository
-variable is `true`, a real V3 Step 1 run also runs **Package V3 candidate
-(shadow)** after the release. It packages the release tag's committed
-bundles into a `v3-candidate-<run id>-<run attempt>` artifact, kept for 7 days.
-It never runs for v2 or dry runs, has read-only access, and its failure does
-not fail the Step 1 run. It does keep the Step 1 run open until it finishes,
-so wait for the whole run to finish before starting Step 2 or Step 3. To turn
-it off, delete the variable or set it to anything other than `true`.
+V3 candidate packaging, upload, and staging: a real **V3 Release - Step 1**
+(`v3-release-step-1.yml`, `dryRun=false`) runs **Package V3 candidate
+(shadow)** after the release to package the release tag's committed bundles
+into a `v3-candidate-<run id>-<run attempt>` artifact (kept for 7 days). Once
+**Publish V3 kits** and **Audit V3 kits on npm** have also succeeded, it runs
+**Upload and stage V3 candidate**, which dispatches **V3 shadow
+release: upload candidate** (`v3-shadow-candidate.yml`) on `main` with
+`release_gate=true` and waits up to 120 minutes (the child jobs' 110-minute
+ceiling plus 10 minutes of queue time, inside a 130-minute job timeout) for it
+to succeed. A failed read of the child run's status (a 5xx or rate-limit reply)
+is retried until that deadline. If the job fails, times out or is cancelled
+before the child run completes, it cancels the child run. A refused cancel (a
+5xx or rate-limit reply) is retried with a doubling backoff (6 tries, 5 seconds
+apart at first) until GitHub accepts it or the child run reads completed, first
+by the wait step and then by the cleanup step. Release-gate dispatches for one
+Step 1 run share one concurrency group (`v3-shadow-candidate-gate-STEP1_RUN_ID`),
+so a re-run's child queues behind a leftover child instead of staging the same
+build in parallel with it. A newer gate dispatch for the same Step 1 run takes
+the group's single pending slot from an older pending one, which then fails its
+own Step 1 wait. A manual dispatch with `release_gate=false` or a transition
+`workflow_run` runs in another group, so it cannot displace a pending gate run.
+
+If the dispatch request succeeds but its reply is lost or carries no
+`workflow_run_id`, the job fails with no child run ID, so nothing cancels that
+child. Before re-running Step 1, open the **V3 shadow release: upload
+candidate** runs, find any run dispatched after the failed Step 1 run started,
+and cancel it if it is still running. If it is missed, the shared concurrency
+group still makes the re-run's child wait for it to finish.
+
+Release-gate mode accepts both an in-progress `v3-release-step-1.yml`
+parent run and one that has already
+completed without being cancelled (so a maintainer can also dispatch
+`v3-shadow-candidate.yml` manually with `release_gate=true` for repair after
+Step 1 finishes), provided **Perform Release** and **Package V3 candidate
+(shadow)** succeeded and one unexpired candidate artifact exists. Release-gate
+mode also requires npm parity to pass: every package must be on npm with the
+candidate's integrity. **Audit V3 kits on npm** only warns about a kit npm does
+not show yet, and npm can take minutes to show a version it has accepted. So
+while npm parity reads pending (a version npm does not show yet) or unavailable
+(an `npm view` error or an unexpected reply), the candidate workflow reads npm
+again with a doubling backoff (15 seconds at first, at most 2 minutes apart)
+for up to 10 minutes, with a last read when the 10 minutes run out. A fail
+reading (a published package with another integrity) fails the gate at once,
+and a read stops at the first package that differs. A package still pending
+or unavailable after the last read fails the gate instead of uploading. Each
+`npm view` gets at most 30 seconds, and each read of every package at most 2
+minutes. A package the read has no time left for reads unavailable. If `sleep`
+fails between reads, the check fails instead of reading npm again at once. A
+transition `workflow_run`, or a manual dispatch with `release_gate=false`,
+reads npm once. The **Check the candidate against the release** job's
+25-minute timeout covers the 10 minutes, a last read of at most 2 minutes and
+its other checks.
+A failure in packaging, candidate verification, S3
+upload, or `v3-staging` pointer staging fails the Step 1 release. In
+release-gate mode, `V3_SHADOW_PODS` must include all five production pods
+(`us1`, `us2`, `st1`, `eu1`, `au1`); `qa` is optional (if `qa` is listed in
+`V3_SHADOW_PODS`, it runs in the same matrix and blocks the release on failure;
+if `qa` is omitted from `V3_SHADOW_PODS`, only the five
+production pods block the release and `qa` can run separately). Stage moves each
+pod's `v3-staging` pointer independently in parallel, so if one pod fails, the
+other pods have already moved to the new candidate; re-running failed jobs on
+Step 1 (within the 7-day artifact window) re-runs **Upload and stage V3
+candidate**, dispatches the candidate workflow again, and repairs the remaining
+pods so every pod converges (`resumeKitReleaseTag` skips packaging and upload
+as before). During the transition before a V3 release's Step 3 brings these
+workflow updates to `main`, the shared **Staging Release - Step 1**
+(`staging-step-1.yml`, `track=v3`) still uses the `V3_PACKAGE_CANDIDATE`
+repository variable and the `workflow_run` trigger on `main`, so
+`V3_PACKAGE_CANDIDATE` stays `true` until that transition release finishes.
 
 ### Recover an incomplete v3 kit publication
 
@@ -238,14 +471,22 @@ 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`
    and the same two inputs instead.
 5. Wait for recovery to verify core and all 33 kits at that version on `next`.
    Existing byte-identical packages are skipped and only missing kits publish.
-6. Continue to Step 2 or Step 3 only after the recovery run is green.
+6. If the failed run was **V3 Release - Step 1**, it did not upload or stage
+   its candidate, because that job waits for the kits. Dispatch **V3 shadow
+   release: upload candidate** (`v3-shadow-candidate.yml`) on `main` with
+   `step1_run_id` set to the failed run's ID and `release_gate=true`, within
+   the candidate's 7 days.
+7. Continue to Step 2 or Step 3 only after the recovery run and the candidate
+   upload are green.
 
 If recovery reports that the tagged core version is missing from npm, stop the
 kit recovery. Semantic-release may have pushed the generated staging commit and
@@ -274,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