docs: forward-port main's versioning (v3.4 archive + label) + archive-link recurrence guard - #22420
Merged
Merged
Conversation
… label)
main's Docusaurus versioning was two transitions stale (current label
'v3.4', versions.json ["v3.3"]), so a release/3.6 cut from main would
inherit a wrong version shelf ("v3.4 current", missing the v3.4 archive).
Bring main to parity with release/3.5's archive set:
- add the frozen v3.4 archive (versioned_docs/version-v3.4/ + its
versioned_sidebars entry), copied verbatim from release/3.5
- add "v3.4" to versions.json (newest-first)
- set the current-version label 'v3.4' -> 'v3.6' (main is the 3.6-dev line)
Deliberately does NOT add a v3.5 archive: v3.5 must be frozen from the
real release/3.5 tip at the 3.6 transition; pre-copying it onto main now
would go stale under backports. See #22416 (section B) for the at-cut step.
Verified: docs/site build green (onBrokenLinks/onBrokenAnchors 'throw');
generate-llms.py --check passes (74 pages, unchanged); v3.4 archive is
byte-for-byte identical to release/3.5 and its static-asset references all
exist on main.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
10 tasks
Contributor
There was a problem hiding this comment.
Pull request overview
Updates main’s Docusaurus versioning state to match the expected shelf for the next release cut by adding the missing v3.4 archive and bumping the “current” label.
Changes:
- Adds
v3.4todocs/site/versions.jsonand introduces the v3.4 archived sidebar. - Adds a large set of
versioned_docs/version-v3.4/**pages to populate the v3.4 archive. - Updates
docs/site/docusaurus.config.tscurrent-version label fromv3.4tov3.6.
Reviewed changes
Copilot reviewed 78 out of 78 changed files in this pull request and generated 11 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/site/versions.json | Adds v3.4 to the archived version list. |
| docs/site/versioned_sidebars/version-v3.4-sidebars.json | Adds sidebar definition for the v3.4 archived docs. |
| docs/site/versioned_docs/version-v3.4/index.mdx | Adds v3.4 archive landing page. |
| docs/site/versioned_docs/version-v3.4/staking/category.json | Adds v3.4 staking category metadata. |
| docs/site/versioned_docs/version-v3.4/staking/index.mdx | Adds v3.4 staking landing page. |
| docs/site/versioned_docs/version-v3.4/staking/caplin.md | Adds v3.4 staking doc (Caplin). |
| docs/site/versioned_docs/version-v3.4/staking/external-consensus-client-as-validator.md | Adds v3.4 staking doc (external CL). |
| docs/site/versioned_docs/version-v3.4/staking/shutter-network.mdx | Adds v3.4 staking doc (Shutter Network). |
| docs/site/versioned_docs/version-v3.4/interacting-with-erigon/category.json | Adds v3.4 RPC reference category metadata. |
| docs/site/versioned_docs/version-v3.4/interacting-with-erigon/index.md | Adds v3.4 RPC reference landing page. |
| docs/site/versioned_docs/version-v3.4/interacting-with-erigon/admin.md | Adds v3.4 RPC reference page (admin). |
| docs/site/versioned_docs/version-v3.4/interacting-with-erigon/bor.md | Adds v3.4 RPC reference page (bor). |
| docs/site/versioned_docs/version-v3.4/interacting-with-erigon/engine.md | Adds v3.4 RPC reference page (engine). |
| docs/site/versioned_docs/version-v3.4/interacting-with-erigon/erigon.md | Adds v3.4 RPC reference page (erigon). |
| docs/site/versioned_docs/version-v3.4/interacting-with-erigon/eth.md | Adds v3.4 RPC reference page (eth). |
| docs/site/versioned_docs/version-v3.4/interacting-with-erigon/graphql.md | Adds v3.4 RPC reference page (graphql). |
| docs/site/versioned_docs/version-v3.4/interacting-with-erigon/grpc.md | Adds v3.4 RPC reference page (gRPC). |
| docs/site/versioned_docs/version-v3.4/interacting-with-erigon/internal.md | Adds v3.4 RPC reference page (internal). |
| docs/site/versioned_docs/version-v3.4/interacting-with-erigon/net.md | Adds v3.4 RPC reference page (net). |
| docs/site/versioned_docs/version-v3.4/interacting-with-erigon/ots.md | Adds v3.4 RPC reference page (ots). |
| docs/site/versioned_docs/version-v3.4/interacting-with-erigon/overlay.md | Adds v3.4 RPC reference page (overlay). |
| docs/site/versioned_docs/version-v3.4/interacting-with-erigon/parity.md | Adds v3.4 RPC reference page (parity). |
| docs/site/versioned_docs/version-v3.4/interacting-with-erigon/txpool.md | Adds v3.4 RPC reference page (txpool). |
| docs/site/versioned_docs/version-v3.4/interacting-with-erigon/web3.md | Adds v3.4 RPC reference page (web3). |
| docs/site/versioned_docs/version-v3.4/get-started/category.json | Adds v3.4 “Get Started” category metadata. |
| docs/site/versioned_docs/version-v3.4/get-started/index.mdx | Adds v3.4 “Get Started” landing page. |
| docs/site/versioned_docs/version-v3.4/get-started/hardware-requirements.mdx | Adds v3.4 hardware requirements page. |
| docs/site/versioned_docs/version-v3.4/get-started/migrating-from-geth.mdx | Adds v3.4 migration guide. |
| docs/site/versioned_docs/version-v3.4/get-started/installation/category.json | Adds v3.4 installation category metadata. |
| docs/site/versioned_docs/version-v3.4/get-started/installation/upgrading.md | Adds v3.4 upgrade guide. |
| docs/site/versioned_docs/version-v3.4/get-started/easy-nodes/category.json | Adds v3.4 easy-nodes category metadata. |
| docs/site/versioned_docs/version-v3.4/get-started/easy-nodes/index.mdx | Adds v3.4 easy-nodes landing page. |
| docs/site/versioned_docs/version-v3.4/get-started/easy-nodes/how-to-run-an-ethereum-node/category.json | Adds v3.4 Ethereum easy-node category metadata. |
| docs/site/versioned_docs/version-v3.4/get-started/easy-nodes/how-to-run-an-ethereum-node/index.md | Adds v3.4 Ethereum easy-node guide. |
| docs/site/versioned_docs/version-v3.4/get-started/easy-nodes/how-to-run-an-ethereum-node/ethereum-with-an-external-cl.mdx | Adds v3.4 Ethereum + external CL guide. |
| docs/site/versioned_docs/version-v3.4/get-started/easy-nodes/how-to-run-a-gnosis-chain-node/category.json | Adds v3.4 Gnosis easy-node category metadata. |
| docs/site/versioned_docs/version-v3.4/get-started/easy-nodes/how-to-run-a-gnosis-chain-node/index.md | Adds v3.4 Gnosis easy-node guide. |
| docs/site/versioned_docs/version-v3.4/get-started/easy-nodes/how-to-run-a-gnosis-chain-node/gnosis-with-an-external-cl.md | Adds v3.4 Gnosis + external CL guide. |
| docs/site/versioned_docs/version-v3.4/get-started/easy-nodes/how-to-run-a-polygon-node.md | Adds v3.4 Polygon easy-node guide. |
| docs/site/versioned_docs/version-v3.4/fundamentals/category.json | Adds v3.4 fundamentals category metadata. |
| docs/site/versioned_docs/version-v3.4/fundamentals/index.mdx | Adds v3.4 fundamentals landing page. |
| docs/site/versioned_docs/version-v3.4/fundamentals/basic-usage.mdx | Adds v3.4 basic usage guide. |
| docs/site/versioned_docs/version-v3.4/fundamentals/caplin.md | Adds v3.4 Caplin guide. |
| docs/site/versioned_docs/version-v3.4/fundamentals/configuring-erigon/category.json | Adds v3.4 CLI-reference category metadata. |
| docs/site/versioned_docs/version-v3.4/fundamentals/configuring-erigon/nat.md | Adds v3.4 NAT configuration guide. |
| docs/site/versioned_docs/version-v3.4/fundamentals/creating-a-dashboard.md | Adds v3.4 monitoring/dashboard guide. |
| docs/site/versioned_docs/version-v3.4/fundamentals/default-ports.md | Adds v3.4 default ports reference. |
| docs/site/versioned_docs/version-v3.4/fundamentals/docker-compose.md | Adds v3.4 Docker Compose guide. |
| docs/site/versioned_docs/version-v3.4/fundamentals/jwt.md | Adds v3.4 JWT secret guide. |
| docs/site/versioned_docs/version-v3.4/fundamentals/layer-2-networks.md | Adds v3.4 L2 networks guide. |
| docs/site/versioned_docs/version-v3.4/fundamentals/logs.md | Adds v3.4 logging guide. |
| docs/site/versioned_docs/version-v3.4/fundamentals/modules/category.json | Adds v3.4 modules category metadata. |
| docs/site/versioned_docs/version-v3.4/fundamentals/modules/index.mdx | Adds v3.4 modules landing page. |
| docs/site/versioned_docs/version-v3.4/fundamentals/modules/downloader.mdx | Adds v3.4 downloader module guide. |
| docs/site/versioned_docs/version-v3.4/fundamentals/modules/rpc-daemon.md | Adds v3.4 RPC daemon module guide. |
| docs/site/versioned_docs/version-v3.4/fundamentals/modules/sentry.mdx | Adds v3.4 sentry module guide. |
| docs/site/versioned_docs/version-v3.4/fundamentals/modules/txpool.md | Adds v3.4 txpool module guide. |
| docs/site/versioned_docs/version-v3.4/fundamentals/multiple-instances.md | Adds v3.4 multi-instance guide. |
| docs/site/versioned_docs/version-v3.4/fundamentals/optimizing-storage.md | Adds v3.4 storage optimization guide. |
| docs/site/versioned_docs/version-v3.4/fundamentals/otterscan.md | Adds v3.4 Otterscan guide. |
| docs/site/versioned_docs/version-v3.4/fundamentals/performance-tricks.md | Adds v3.4 performance tuning guide. |
| docs/site/versioned_docs/version-v3.4/fundamentals/prune-modes.md | Adds v3.4 prune modes guide. |
| docs/site/versioned_docs/version-v3.4/fundamentals/security.md | Adds v3.4 security guidance. |
| docs/site/versioned_docs/version-v3.4/fundamentals/supported-networks.md | Adds v3.4 supported networks reference. |
| docs/site/versioned_docs/version-v3.4/fundamentals/tls-authentication.md | Adds v3.4 TLS authentication guide. |
| docs/site/versioned_docs/version-v3.4/fundamentals/web3-wallet.md | Adds v3.4 web3 wallet guide. |
| docs/site/versioned_docs/version-v3.4/about/category.json | Adds v3.4 about category metadata. |
| docs/site/versioned_docs/version-v3.4/about/index.mdx | Adds v3.4 about landing page. |
| docs/site/versioned_docs/version-v3.4/about/contributing.md | Adds v3.4 contributing page. |
| docs/site/versioned_docs/version-v3.4/about/disclaimer.md | Adds v3.4 disclaimer page. |
| docs/site/versioned_docs/version-v3.4/about/license.md | Adds v3.4 license page. |
| docs/site/docusaurus.config.ts | Bumps current-version label to v3.6. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
bloxster
pushed a commit
that referenced
this pull request
Jul 13, 2026
The frozen v3.4 archive used unversioned absolute links (e.g. `/get-started/`) copied from the current docs. Inside an archive those resolve to the *current* version, bouncing readers out of the v3.4 snapshot (flagged by Copilot on #22420; root cause #22416). The v3.3 archive was already self-contained; v3.4 was not. Fix (76 links / 13 files): cross-page absolute links -> `/v3.4/`-prefixed, same-page anchors -> local `#frag`. Left `/`, `/help-center/…`, `/img/…`, external and already-`/vX.Y/` links untouched. Prevention (docs/site/scripts/): - fix-archive-links.py — reusable fixer + `--check`; per version it prefixes any unversioned absolute intra-docs link and localizes same-page anchors. Handles markdown/reference/JSX/HTML link forms, skips fenced code, and flags links into renamed/removed sections (the silent-leak blind spot). Run it after `docusaurus docs:version`. - test_archive_links.py — guard: fails if any archived version has an unversioned absolute link. Auto-runs via the existing `unittest discover docs/site/scripts` step (no workflow change). - test_fix_archive_links.py — unit tests for each link syntax/edge case. Verified: build green (onBrokenLinks 'throw'); llms --check unchanged (74 pages); 62 unittests pass; guard catches all 76 on the pre-fix archive. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…se/3.5) Replaces the verbatim-copied v3.4 archive on this branch with the self-contained version (unversioned absolute links -> /v3.4/-prefixed; same-page anchors -> local), and adds the archive-link fixer + CI guard, identical to the release/3.5 companion (#22426). Addresses the Copilot review on this PR and closes the recurrence path (#22416). Verified on main: build green; llms --check unchanged (74 pages); 62 unittests pass; guard reports the archives self-contained. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Collaborator
Author
|
@copilot all 11 flagged v3.4 archive links are fixed in 9c45d44: cross-page absolute links are now To prevent recurrence I also added |
Contributor
Verified — all remaining open threads are resolved in 9c45d44. Both the namespace links in |
bloxster
changed the title
…/3.5) Same script fixes as #22426: preserve full fence length in code-block detection (4+ backtick fences), and use context managers + UTF-8 in the test helper (+ 4-backtick regression test). Keeps main's scripts identical to release/3.5. 63 unittests pass; ruff clean. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
bloxster
marked this pull request as ready for review
July 13, 2026 09:22
AskAlexSharov
approved these changes
Jul 20, 2026
github-merge-queue Bot
pushed a commit
that referenced
this pull request
Jul 20, 2026
#22426) ## What The frozen **v3.4 archive** used unversioned absolute links (e.g. `/get-started/`) that were copied from the current docs. Inside an archived version those resolve to the **current** version, so a reader browsing the v3.4 docs is silently bounced into v3.5/v3.6. GitHub Copilot flagged this on #22420; the root cause is tracked in #22416. The v3.3 archive was already self-contained — v3.4 was the outlier (#22062 only fixed the links that broke the build). **Fix (76 links / 13 files):** cross-page absolute links → `/v3.4/`-prefixed (matching v3.3); same-page anchors → local `#frag`. Left `/` (home), `/help-center/…` (separate unversioned instance), `/img/…`, external, and already-`/vX.Y/` links untouched. ## Prevention (so future version cuts can't reintroduce this) Three files under `docs/site/scripts/`: - **`fix-archive-links.py`** — reusable fixer + `--check`. Per archived version it prefixes any unversioned absolute intra-docs link and localizes same-page anchors. Handles markdown inline/reference, JSX `<Link>`, and HTML `<a href>` forms; skips fenced code; and flags links into **renamed/removed** sections (the silent-leak case `onBrokenLinks` can miss). Run it right after `docusaurus docs:version vX.Y`. - **`test_archive_links.py`** — the guard: fails if any `versioned_docs/version-*/` page has an unversioned absolute intra-docs link. It **auto-runs in CI** via the existing `python3 -m unittest discover docs/site/scripts` step in `docs-site-build.yml` (PR) and `docs-deploy.yml` (push) — **no workflow change**, and it runs before the npm build so neither path can bypass it. - **`test_fix_archive_links.py`** — unit tests for each link syntax and edge case. ## Verification - `docs/site` build **green** (`onBrokenLinks`/`onBrokenAnchors`/`onBrokenMarkdownLinks` all `'throw'`). - `generate-llms.py --check` unchanged (74 pages — generator ignores `versioned_docs/`). - **62 unittests pass**; the guard catches all **76** links on the pre-fix archive (has teeth); fixer is idempotent and reproducible. - v3.3 archive already passes the guard. ## Review Adversarially reviewed by ChatGPT 5.5 + Fable (both APPROVE-WITH-CHANGES). All findings folded in: broadened link-form coverage, catch-all detection (fixes the renamed-section blind spot), fenced-code skipping, `to=` word boundary (won't match `photo=`/`auto=`), root-`index` `/#frag` localization, and `argparse`. Companion: #22420 carries the same corrected v3.4 archive + these scripts to `main`. Refs #22416, #22420. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Bloxster <gianni.morselli@erigon.tech> Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
main's Docusaurus versioning was two transitions stale: current label'v3.4'andversions.json = ["v3.3"](only the v3.3 archive). Because release branches are cut frommain, a futurerelease/3.6cut would inherit this wrong shelf — the site would come back labelled "v3.4 current" and missing the v3.4 archive. This bringsmainto parity withrelease/3.5's archive set (addresses section A of #22416):versioned_docs/version-v3.4/+versioned_sidebars/version-v3.4-sidebars.json), copied verbatim fromrelease/3.5"v3.4"toversions.json(newest-first →["v3.4","v3.3"])'v3.4'→'v3.6'versioned_docs/version-v3.4/: cross-page absolute links are now/v3.4/-prefixed and same-page anchors are local#…(matching the v3.3 archive pattern), keeping navigation within the v3.4 snapshot (76 links across 13 files)mainisn't deployed today (the live site builds fromrelease/3.5), so this is inert until arelease/3.6cut — but it makes that cut inherit a correct shelf.Deliberately NOT included: a v3.5 archive
v3.5 is the current stable — it lives as
release/3.5's current, not an archive. It must be frozen from the realrelease/3.5tip at the 3.6 transition; pre-copying it ontomainnow would go stale asrelease/3.5keeps taking backported doc fixes. That at-cut step is tracked in #22416 (section B).Decision needed:
'v3.6'vs'Next'I used
label: 'v3.6'— it matches the repo convention (each branch labels its series) and means arelease/3.6cut inherits the correct label with zero edits. Trade-off: it re-stales the momentrelease/3.6is cut (mainbecomes 3.7-dev while still labelled'v3.6') — the exact failure mode this PR fixes. The alternative,'Next', never goes stale and is idiomatic for an unreleased current version, at the cost of one relabel at cut. Happy to switch to'Next'if preferred; otherwise "bumpmain's label" should join the at-cut checklist in #22416.Verification
docs/siteDocusaurus build green (onBrokenLinks/onBrokenAnchors/onBrokenMarkdownLinksall'throw') — the v3.4 archive builds cleanly againstmain's current docs.generate-llms.py --checkpasses, unchanged (74 pages — the generator ignoresversioned_docs/)./img/{eth,gno,pol,shutter}.svg) all exist onmain(no silent 404).versions.json-driven config wires{ERIGON_VERSION}for v3.4 with no per-version edit (same mechanism asrelease/3.5).docs/site/scripts/test_archive_links.pyguard added: fails CI (via the existingunittest discoverstep) if any archived version contains an unversioned absolute intra-docs link, preventing recurrence. 62 unittests pass.Refs #22416.