[pull] master from apify:master

RELEASE.md

@@ -46,3 +46,51 @@ released commit; no version-bump commit lands on the branch.
 See the tracking issue for the ordered checklist (publish 4.0.0 to `latest`, switch
 master canaries `v4` → `next` and `--canary=major` → `--canary=patch`, switch 3.x to
 `latest-v3`/`next-v3`, drop the RC docs label).
+
+## Playbook: switching master to the next major
+
+Notes from the v4 transition (August 2026), for whoever does v5. The overall flow: develop
+the next major on a `vN` branch (canaries under the `vN` dist-tag, RCs under `rc`), and when
+it is time to make it the main line, cut a maintenance branch and fast-forward master.
+
+1. **Cut the maintenance branch first.** Branch `(N-1).x` off the master tip. In one commit,
+   adapt its workflows: `test-ci.yml` triggers and the `release_next` gate point at the
+   branch (use exact `github.ref == 'refs/heads/(N-1).x'` matching, not `contains()` — the
+   substring match is a footgun), and delete the `version-docs` job from `release.yml`
+   (it checks out the repo default branch, so on a maintenance branch it would snapshot the
+   wrong docs). Canaries keep the `next` tag and stable releases keep `latest` until the new
+   major actually ships.
+2. **Rebase the `vN` branch onto the master tip** and validate: no conflict markers, tree
+   diff vs the old `vN` tip only shows what you expect, full build, `tsc-check-tests`,
+   `api:check`, test suite, website build. Watch for master-only features silently lost in
+   the rebase — compare public API snapshots (`docs/public-api/`), and re-check any file
+   both lines touched heavily.
+3. **Docs.** Delete the dev snapshot (`website/versioned_docs/version-N.0`, its sidebars
+   file, and the `versions.json` entry) — the dev docs become the unversioned "current"
+   version, labeled via `versions.current.label` (`'N.0 (RC)'`) in `docusaurus.config.js`.
+   The previous major stays the default docs version until the stable release, whose
+   `version-docs` job creates the real `N.0` snapshot. Gotchas: the latest snapshot is
+   served *unversioned* at `/js/api`, so hardcoded `/js/api/N-1.x/...` links (blog posts,
+   snapshot edits from the dev branch) break once the dev snapshot is gone, and package
+   READMEs that link to new-major API pages need `/js/api/next/...` until the major is the
+   default. `ApiLink.jsx` and `NavbarItem/ComponentTypes.js` must both derive the stable
+   version from `versions.json[0]`.
+4. **Fast-forward push master.** A PR cannot do this: the org ruleset only allows squash
+   merges into master, and a squash (or GitHub's rebase-merge) would rewrite the history.
+   Direct pushes are blocked by three rulesets — org "Important branches PR enforcement",
+   org "Allow only squash merges…" (its `pull_request` rule also enforces PR-only pushes),
+   and repo "Require CI checks on master" — all of which accept the `BypassTemporary` team,
+   so join it for the duration of the push (the last two needed the team added in the v4
+   round; check they still have it).
+5. **Retarget the open `vN`-based PRs to master yourself** (`gh pr edit --base master`)
+   before deleting the `vN` branch. GitHub only auto-retargets when the base branch is
+   deleted after being merged through a PR; after a fast-forward push, deleting the branch
+   would auto-close them instead.
+6. **Update the required status checks** on the "Require CI checks on master" ruleset if the
+   Node matrix changed, and check Renovate/Dependabot: the dev branch's lockfile format wins
+   after the merge, and dependency bumps that renovate landed on old-master meanwhile may
+   need re-applying (a stale peer-keyed lockfile entry can surface as bogus type errors —
+   `pnpm dedupe` fixes that).
+7. **Open the release-day tracking issue** (see the v4.0.0 section above for the shape) and
+   keep the dist-tag flips in it — the maintenance branch must move off `latest` the same
+   day the new major claims it.

package.json

@@ -125,7 +125,7 @@
         "playwright": "1.61.1",
         "portastic": "^1.0.1",
         "proxy": "^2.2.0",
-        "puppeteer": "25.3.0",
+        "puppeteer": "25.8.0",
         "rimraf": "^6.0.1",
         "tsx": "^4.19.4",
         "turbo": "^2.5.3",