@mparticle/web-sdk 3.29.0 → 3.30.0

package/README.md

@@ -144,14 +144,32 @@ This package comes with the NPM package [pre-commit](https://www.npmjs.com/packa
 
 ## Three-step release process (maintainers)
 
-Releases have separate v2 and v3 tracks. In GitHub Actions, choose the
-track-specific branch from the **Use workflow from** dropdown and run these
-workflows in order:
-
-1. **Staging Release - Step 1: Prepare CDN Pre-Release, Publish NPM**
-   (`staging-step-1.yml`): select `staging` for `track=v2`, or `v3-staging` for
-   `track=v3`. This workflow builds and tests the track, creates and merges a
-   generated release branch, runs semantic-release, and publishes the npm
+V2 and V3 release with separate workflows: `staging-step-1.yml`,
+`staging-step-2.yml` and `staging-step-3.yml` for v2, and
+`v3-release-step-1.yml`, `v3-release-step-2.yml` and `v3-release-step-3.yml`
+for v3.
+
+During the switch to the V3 files, `staging-step-1.yml` keeps its `v3` track
+and kit recovery. The first V3 release after the split still runs it from
+`v3-staging` with `track=v3`, because `v3-release-step-1.yml` reaches `main`
+only at that release's Step 3. If that release's kit publishing fails, resume
+it with **Staging Release - Step 1** from `v3-staging` (`track=v3`,
+`dryRun=false`, `resumeKitReleaseTag`). The same release runs Steps 2 and 3
+with **Staging Release - Step 2** and **Staging Release - Step 3** from `main`,
+because `v3-release-step-2.yml` and `v3-release-step-3.yml` also reach `main`
+only at its Step 3. Once a V3 release has run on
+`v3-release-step-1.yml`, a follow-up removes the `v3` track from
+`staging-step-1.yml`. V2 runs the copies on `staging` and `master`, which this
+split does not change.
+
+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
+   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`
    bootstrap permits all kit tags to be absent so the first synchronized release
@@ -172,26 +190,27 @@ workflows in order:
    identical. `dryRun=true` previews the merge and semantic-release result
    without creating a branch or publishing; `dryRun=false` creates/pushes the
    release branch and publishes. If core publishes but kit publication cannot
-   finish, rerun Step 1 from `v3-staging` with `track=v3`, `dryRun=false`, and
+   finish, rerun V3 Release - Step 1 from `v3-staging` with `dryRun=false` and
    `resumeKitReleaseTag` set to the exact Step 1 tag. Recovery validates that
    immutable tag and resumes kits without republishing core.
-2. **Staging Release - Step 2: Publish SDK Release to Release Order Branch**
-   (`staging-step-2.yml`, optional): select `master` for v2 or `main` for v3.
-   Every run, dry runs included, rejects a `v2.x` tag dispatched from anything
-   but `master` and a `v3.x` tag from anything but `main`. For `releaseTag`,
-   enter the exact Git tag created by the successful Step 1 run (for example,
-   `v2.80.0` or `v3.0.1`). Choose
+2. **Step 2: Publish SDK Release to Release Order Branch** (optional): run
+   **Staging Release - Step 2** (`staging-step-2.yml`) from `master` for v2, or
+   **V3 Release - Step 2** (`v3-release-step-2.yml`) from `main` for v3. Every
+   run, dry runs included, rejects the other version's tag and a dispatch from
+   any other branch. For `releaseTag`, enter the exact Git tag created by the
+   successful Step 1 run (for example, `v2.80.0` or `v3.0.1`). Choose
    `release-order-a`, `-b`, or `-c` as `releaseOrderBranch`. For v3, that
    logical choice maps to the corresponding `v3-release-order-*` branch.
    `dryRun=true` validates the exact candidate and fast-forward without
    pushing; `dryRun=false` promotes it.
-3. **Staging Release - Step 3: Release to CDN and Synchronize Branches**
-   (`staging-step-3.yml`): select `master` for v2 or `main` for v3, with the
-   same per-track rule as Step 2. For `releaseTag`, enter the same exact Git
+3. **Step 3: Release to CDN and Synchronize Branches**: run
+   **Staging Release - Step 3** (`staging-step-3.yml`) from `master` for v2, or
+   **V3 Release - Step 3** (`v3-release-step-3.yml`) from `main` for v3, with
+   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 current track staging head, and can
+   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 track's development branch, trunk (`master` or `main`), and all three
+   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.
@@ -201,14 +220,75 @@ 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 `track=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
 
@@ -219,11 +299,20 @@ 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 **Staging Release - Step 1** from `v3-staging` with `track=v3`,
-   `dryRun=false`, and `resumeKitReleaseTag` set to the failed run's exact tag.
+4. 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
@@ -243,14 +332,23 @@ If core's `next` tag changes without a corresponding Step 1 Git tag, do not use
 the bootstrap exception or guess a recovery tag. Stop releases and reconcile
 the unexpected npm and Git state before continuing.
 
-Each track's trunk owns its own copy of the release workflows: `master` for v2
-and `main` for v3. The copies may differ, so a change to one track's release
-steps does not need a twin on the other trunk. Steps 2 and 3 run from the
-dispatching trunk, and the per-track rule above keeps each track on its own
-trunk's copy. GitHub executes Step 1 from the branch selected in the **Use
-workflow from** dropdown, so every `dryRun=false` Step 1 run rejects the
-release unless `staging-step-1.yml` on the staging branch is identical to its
-trunk's copy: `staging` to `master`, and `v3-staging` to `main`.
+Each version's trunk owns its own copy of its release workflows: `master` for
+v2 and `main` for v3. A change to one version's release steps does not need a
+twin on the other trunk. Steps 2 and 3 run from the dispatching trunk, and the
+rule above keeps each version on its own trunk's copy. GitHub executes Step 1
+from the branch selected in the **Use workflow from** dropdown, so every
+`dryRun=false` Step 1 run rejects the release unless its workflow on the
+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.
+
+npm trusted publishing names the workflow file that publishes each package:
+`staging-step-1.yml` publishes v2 of `@mparticle/web-sdk`, and
+`v3-release-step-1.yml` publishes v3 of `@mparticle/web-sdk` and every kit in
+`kits/publish-matrix.json`. Until a V3 release has run on
+`v3-release-step-1.yml`, each of those packages keeps `staging-step-1.yml` as a
+trusted publisher too, so the first V3 release after the split can publish.
 
 ## Support