ci(docs): auto-archive previous docs version when a release branch is cut

[bloxster]

What

Adds an archive-previous-docs-version job to create-release-branch.yml that runs right after a release/N.N branch is cut and opens a docs-labelled PR archiving the previous stable docs version onto the freshly-cut branch (Docusaurus native versioning). A human reviews and merges that PR.

This automates Q1 of the docs version transition (archive the outgoing version). Q2 — flipping the live deploy on docs.erigon.tech to the new series — is intentionally left as the existing manual retire+publish pair (#22062 / #22063).

Why

Versioning is not automatic today: cutting release/3.6 leaves versions.json without a v3.5 snapshot, so the previous stable version would silently drop out of the version dropdown. Doing it by hand is easy to forget or get wrong.

How it works

• Sources the snapshot from the OUTGOING release branch (release/N.<M-1>), not the just-cut branch — which was cut from main and already holds the next version's docs. (This is the correctness bug the manual docs-version-bump.yml path is prone to.)
• Ports the outgoing branch's full versioned state (versions.json + all versioned_docs/ + versioned_sidebars/) plus the fresh snapshot, then enforces the 3-archived-version cap — so no older version drops off at the next cut.
• Fail-closed series selection: enumerates release/N.N branches via the GitHub API, exact regex (excludes patch-style names like release/3.0.10), numeric per-component sort (so 3.10 > 3.9); aborts on API error rather than guessing.
• Build-verified before opening (onBrokenLinks: throw), llms.txt regenerated.
• dry_run validates the full port + build without opening a PR.
• Opens the PR with the default GITHUB_TOKEN (scoped contents:write + pull-requests:write) for manual review/merge. Note: a GITHUB_TOKEN-opened PR does not itself trigger pull_request CI (Actions recursion guard); the archive is already build-verified in-job, and a reviewer merges after inspecting the diff.

Notes for reviewers

• The version chain stays intact only if each cycle's archive PR is merged into its release branch before the next cut (inherent to the human-merge model; no worse than today's fully-manual state).
• Passed actionlint (with shellcheck) and zizmor locally.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds an automated “Q1” docs-version transition step to the release-branch cut workflow, so the outgoing stable docs version is archived onto the newly cut release/N.N branch via an automatically opened, docs-labelled PR (build-verified before opening).

Changes:

• Introduces a new archive-previous-docs-version job that determines the outgoing release series, snapshots its docs via Docusaurus versioning, ports the full versioned docs state, enforces the archived-version cap, regenerates llms artifacts, and build-verifies.
• Opens a PR against the newly cut release branch (or validates end-to-end in dry_run without opening a PR).
• Extends the Discord notification embed to include a “Docs archive” audit field.

Comments suppressed due to low confidence (1)

.github/workflows/create-release-branch.yml:401

• The Discord notification summary treats any non-skipped / non-PR-opened state as n/a. With the dry-run validation path, this will hide useful information (it should explicitly report that the docs archive was validated without opening a PR).

          if [ -n "${ARCHIVE_PR_URL:-}" ]; then
            archive_field="[Archive PR opened]($ARCHIVE_PR_URL)"
          elif [ "${ARCHIVE_OUTCOME:-}" = "skipped" ]; then
            archive_field=":information_source: ${ARCHIVE_DETAIL:-skipped}"
          else

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[bloxster]

Blocked by flaky merge-group CI — requesting a maintainer merge

This PR is CLEAN + APPROVED and passes every required check on its head, but it has been evicted from the merge queue three times, each time due to merge-group CI infrastructure that is unrelated to the change (this PR only edits .github/workflows/create-release-branch.yml and docs-version-bump.yml):

Attempt	Merge-group run	Outcome
1	pr-22691 @ 14:56	merge-group cancelled early
2	run 30020468417 @ 15:25	kurtosis / assertoor_pectra_serial_test hung and hit the 60-min timeout (15:34:34 → 16:34:51), failing ci-gate → evicted
3	run 30027885641 @ 17:04	all hive-eest jobs mass-cancelled ~11 min in → evicted

The assertoor_pectra_serial_test job that timed out in attempt 2 passed in a sibling PR's merge-group (#22694) with the same code path, confirming it's a flaky/hanging test rather than a real failure. The heavy merge-group suite (kurtosis, hive-eest) is not exercised by a docs-workflow-only change.

Could a maintainer with admin please either:

1. Merge this directly (bypassing the flaky queue), or
2. Exempt docs/workflow-only PRs from the heavy merge-group required checks?

Happy to rebase if needed. cc @lystopad