docs(hardware): make disk sizes static (fix versioned-docs drift) by bloxster · Pull Request #22596 · erigontech/erigon

bloxster · 2026-07-20T06:12:40Z

What & why

The hardware-requirements "Current Disk Usage" numbers were pulled at runtime from one shared disk-sizes.json. Every docs version imported the same file, so the /v3.4/ page showed the current numbers instead of 3.4's — and a missing value silently showed —.

This makes the numbers static text instead, so each docs version keeps its own correct values.

How it works now

Values live directly in the page between tiny markers: {/* ds:mainnet:full */}920 GB{/* ds:end */}.
scripts/render-disk-sizes.py fills those markers from disk-sizes.json. CI runs it with --check and fails the build if the page and JSON disagree, or if any page still imports the JSON.
Because the page is static, docusaurus docs:version now freezes the right numbers automatically — no extra step at release time.

Changes

Current + v3.4 hardware pages: static values + a "measured as of" date; runtime import removed. (v3.4 shows real 3.4 numbers again.)
New render-disk-sizes.py + tests (fail-closed: rejects typo'd/unpaired markers, bad dates, unsafe values).
CI (docs-site-build.yml): render check + guard against dynamic references.
update-disk-sizes.yml: renders the page after updating the JSON; also dropped a broken trigger and fixed the target branch to release/3.5.
README: documents the flow; fixes stale release/3.4 deploy references.
llms-full.txt: now shows real values instead of —.

Not in this PR

Refreshing the current v3.5 numbers (waiting on a node sync) — separate PR.
Forward-porting to main.

Verification

render --check, guard, 56 script tests, generate-llms.py --check, typecheck, and build all pass. Reviewed by Copilot (2 comments fixed) + a focused adversarial pass (hardening folded in).

🤖 Generated with Claude Code

Versioned hardware-requirements pages imported the shared, live src/data/disk-sizes.json, so `docusaurus docs:version` snapshots kept tracking the current file instead of freezing the numbers measured for that release (the deployed /v3.4/ page showed current values). The runtime import also hid a silent `?? '—'` fallback — visible in the old llms-full.txt, which rendered "—" for every disk size. Switch to static values held between MDX-comment markers, kept in sync with the JSON by a render step: - docs/get-started/hardware-requirements.mdx: replace dynamic {diskSizes...} cells with static `{/* ds:net:mode */}VALUE{/* ds:end */}` markers + a "measured as of" date note; drop the runtime import. - scripts/render-disk-sizes.py (+ tests): project disk-sizes.json onto the markers; `--check` fails if they drift. CI runs it after updating the JSON and commits the page. - versioned_docs/version-v3.4: freeze to the measured 3.4 values as static text (supersedes #22583) so the guard holds and /v3.4/ shows 3.4 numbers. - docs-site-build.yml: verify markers in sync (--check) and fail-closed if any docs/ or versioned_docs/ page references diskSizes / imports the JSON. - update-disk-sizes.yml: render the page after updating the JSON; commit both. - README: document the disk-size data flow + simplified version-cut runbook, and fix stale deploy-branch references (release/3.4 -> release/3.5). - Regenerate llms-full.txt (now shows real values instead of "—"). Because the current page is now static, `docs:version` snapshots freeze correct values by construction — no per-cut freeze step needed. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

This PR fixes “versioned docs drift” for the hardware requirements page by removing runtime imports of disk-sizes.json and replacing them with static values embedded in MDX markers, kept in sync by a renderer script and enforced by CI. This ensures docusaurus docs:version snapshots freeze the correct per-release disk usage numbers.

Changes:

Replace dynamic {diskSizes...} lookups with static marker-wrapped values in the current and v3.4 hardware requirements pages, and add “measured as of” notes.
Add render-disk-sizes.py plus unit tests to project disk-sizes.json onto MDX markers; wire --check into docs build CI.
Update workflows/docs artifacts so disk-size updates render the page and CI fails if dynamic disk-size references reappear.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
`docs/site/docs/get-started/hardware-requirements.mdx`	Switches from runtime JSON import to static marker-wrapped disk usage values + date markers.
`docs/site/versioned_docs/version-v3.4/get-started/hardware-requirements.mdx`	Freezes v3.4 page with static 3.4-era values (no runtime import).
`docs/site/scripts/render-disk-sizes.py`	New renderer that updates marker-wrapped values from `disk-sizes.json` and supports `--check`.
`docs/site/scripts/test_render_disk_sizes.py`	Unit tests for marker rendering, idempotence, and fail-closed behavior.
`.github/workflows/docs-site-build.yml`	Adds `render-disk-sizes.py --check` and a guard that rejects dynamic disk-size references.
`.github/workflows/update-disk-sizes.yml`	After updating JSON, renders the MDX page and commits both JSON + page changes.
`docs/site/README.md`	Documents disk-size data flow and updates deploy branch reference to `release/3.5`.
`llms-full.txt`	Regenerated LLM artifact showing concrete disk sizes instead of `—`.
`docs/site/static/llms-full.txt`	Same regenerated LLM artifact under docs site static assets.

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

Bring the release/3.5 copy in line with main's maintained determine logic and the static-markers flow: - Trigger on the dedicated producers "(minimal node)" and "(full node)"; drop the broken plain "QA - Sync from scratch" trigger (matches #22556): it emits no disk-usage-* artifact, so it only ever fired a failing run. - Adopt main's determine logic: minimal -> minimal, full node -> full, else -> ::error:: (explicit guard, not a silent "full" fallback). - Fix base_branch release/3.4 -> release/3.5 (workflow_run paths + the workflow_dispatch default): docs deploy from release/3.5 now. Note: on release/3.5 this workflow is only reachable via manual workflow_dispatch — workflow_run events run the copy from the default branch (main). The render-disk-sizes.py step added here therefore also needs to land on main's update-disk-sizes.yml to keep CI-generated disk-size PRs in sync with the static markers. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

- docs-site-build.yml: make the dynamic-reference guard truly fail-closed by checking grep's exit code explicitly (0=match→fail, 1=no match→ok, 2+=error→fail). An `if grep …; then` alone swallowed grep errors (exit 2, e.g. missing dir/IO) as "no match". - render-disk-sizes.py: read/write JSON and the MDX page as explicit UTF-8 so behavior is locale-independent (the page contains em-dashes/unicode). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…w-up) A focused adversarial review found the fail-closed guard wasn't fully fail-closed and a couple of silent-wrong-output paths. Harden render_text: - Completeness guard: every disk-size marker comment must belong to a well-formed value/date pair, else hard error. Catches spacing typos, markers wrapped across a newline, nesting, and dangling closers — which previously were silently skipped, so a cell could go stale while `render --check` stayed green (the exact failure the design prevents). - Validate measured_at as zero-padded YYYY-MM-DD and use min() (oldest) for the "measured as of" caption. max() over raw strings was lexicographic (e.g. "2026-6-2" > "2026-11-15") and overstated freshness. - Validate display: non-empty string, no braces/newlines (avoids blank cells and MDX/marker corruption). - Clean SystemExit for malformed JSON and non-dict mode entries instead of raw tracebacks. Adds unit tests for each fail-closed case. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.

lystopad · 2026-07-20T08:29:25Z

  workflow_run:
    workflows:
-      - "QA - Sync from scratch"
      - "QA - Sync from scratch (minimal node)"
+      - "QA - Sync from scratch (full node)"
    types:


Agree with it.
Same change as #22556 , but your changes are addressed to release/3.5.

Thanks both — confirmed QA - Sync from scratch (full node) exists on main but not on release/3.5. The important context: this update-disk-sizes.yml is effectively inert on release/3.5 — workflow_run executes the copy on the default branch (main), and no release/3.5 producer emits disk-usage-* artifacts, so its only reachable path here is a manual workflow_dispatch.

Since #22596 is already in the merge queue, I'm leaving this file at the release/3.5 baseline and moving the actual workflow change (render step + trigger cleanup, matching #22556) to main's forward-port — where the pipeline runs and (full node) exists. Happy to scrub release/3.5's copy too in a follow-up if you'd prefer parity.

lystopad · 2026-07-20T08:30:04Z

+            # Map the producing workflow → the mode it measured:
+            #   "QA - Sync from scratch (minimal node)" → minimal
+            #   "QA - Sync from scratch (full node)"    → full
+            if [[ "$WORKFLOW_RUN_NAME" == *"minimal"* ]]; then
+              MODE=minimal
+            elif [[ "$WORKFLOW_RUN_NAME" == *"full node"* ]]; then
+              MODE=full
+            else
+              echo "::error::Unexpected producing workflow: $WORKFLOW_RUN_NAME"
+              exit 1
+            fi


"QA - Sync from scratch" is wrong, you need to use QA - Sync from scratch (full node) instead.
See previous comment.

Same as the trigger thread: this mapping is on release/3.5's inert copy of the workflow (runs only via manual dispatch). The correct (full node) mapping will land on main's update-disk-sizes.yml in the forward-port alongside #22556; leaving release/3.5's copy unchanged here.

…to main) (erigontech#22628) Forward-port of erigontech#22596 (merged to `release/3.5`) to `main`. ## What & why The hardware-requirements "Current Disk Usage" numbers were pulled at runtime from one shared `disk-sizes.json`. Every docs version imported the **same** file, so the `/v3.4/` page showed the **current** numbers instead of 3.4's — and a missing value silently rendered `—`. This makes the numbers **static text**, so each docs version keeps its own correct values. ## How it works now - Values live in the page between markers: `{/* ds:mainnet:full */}920 GB{/* ds:end */}`. - `scripts/render-disk-sizes.py` fills those markers from `disk-sizes.json`. CI runs it with `--check` and **fails the build** if the page and JSON disagree, or if any page still imports the JSON. - Because the page is static, `docusaurus docs:version` freezes the right numbers automatically — no extra step at release time. ## Changes - Current + **v3.4** hardware pages: static values + "measured as of" date; runtime import removed. - New `render-disk-sizes.py` + tests (fail-closed on typo'd/unpaired markers, bad dates, unsafe values). - CI (`docs-site-build.yml`): render `--check` + guard against dynamic references. (Keeps main's `checkout@v7` / `persist-credentials` / `timeout-minutes`.) - `update-disk-sizes.yml`: **only** adds the render step + commit-both. Main's app-token infra (erigontech#22547), trigger cleanup (erigontech#22556), and `base_branch=release/3.5` are preserved. This is also where the main-side workflow change from the erigontech#22596 discussion lands. - README: documents the data flow + version-cut runbook. - `llms-full.txt`: regenerated (real values instead of `—`). ## Verification `render --check`, guard, **78 script tests**, `generate-llms.py --check`, typecheck, and build all pass. Ported content is byte-identical to merged erigontech#22596; adversarially reviewed for merge correctness (main-only workflow features confirmed preserved). ## Note `update-disk-sizes` dispatched against a base branch that lacks `render-disk-sizes.py` (e.g. retired `release/3.4`) now fails at the render step — fail-loud and expected. 🤖 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>

bloxster requested review from AskAlexSharov, lystopad, mriccobene and yperbasis as code owners July 20, 2026 06:12

bloxster mentioned this pull request Jul 20, 2026

docs(hardware): freeze v3.4 disk sizes as static values #22583

Closed

bloxster requested a review from Copilot July 20, 2026 06:14

Copilot started reviewing on behalf of bloxster July 20, 2026 06:14 View session

Copilot AI reviewed Jul 20, 2026

View reviewed changes

Comment thread .github/workflows/docs-site-build.yml Outdated

Comment thread docs/site/scripts/render-disk-sizes.py Outdated

Bloxster and others added 3 commits July 20, 2026 08:38

bloxster changed the title ~~docs(hardware): make disk sizes static, fix versioned-docs drift~~ docs(hardware): make disk sizes static (fix versioned-docs drift) Jul 20, 2026

AskAlexSharov approved these changes Jul 20, 2026

View reviewed changes

AskAlexSharov requested a review from Copilot July 20, 2026 08:18

AskAlexSharov enabled auto-merge July 20, 2026 08:18

Copilot started reviewing on behalf of AskAlexSharov July 20, 2026 08:19 View session

Copilot AI reviewed Jul 20, 2026

View reviewed changes

AskAlexSharov added this pull request to the merge queue Jul 20, 2026

github-merge-queue Bot removed this pull request from the merge queue due to failed status checks Jul 20, 2026

bloxster added this pull request to the merge queue Jul 20, 2026

Merged via the queue into release/3.5 with commit 9e85653 Jul 20, 2026
100 checks passed

bloxster deleted the docs/disk-sizes-static-markers branch July 20, 2026 13:20

bloxster mentioned this pull request Jul 21, 2026

docs(hardware): make disk sizes static (forward-port #22596 to main) #22628

Merged

erigon-copilot Bot mentioned this pull request Jul 24, 2026

[SharovBot] ci: restore scripts from base branch to fix render-disk-sizes.py not found #22719

Open

bloxster mentioned this pull request Aug 3, 2026

docs: port the docs backlog to release/3.6 ahead of the deploy cutover #22970

Merged

Navigation Menu

Uh oh!

docs(hardware): make disk sizes static (fix versioned-docs drift) - #22596

docs(hardware): make disk sizes static (fix versioned-docs drift)#22596
bloxster merged 4 commits into
release/3.5from
docs/disk-sizes-static-markers

bloxster commented Jul 20, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

lystopad Jul 20, 2026

Uh oh!

bloxster Jul 20, 2026

Uh oh!

lystopad Jul 20, 2026

Uh oh!

bloxster Jul 20, 2026

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

bloxster commented Jul 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What & why

How it works now

Changes

Not in this PR

Verification

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

lystopad Jul 20, 2026

Choose a reason for hiding this comment

Uh oh!

bloxster Jul 20, 2026

Choose a reason for hiding this comment

Uh oh!

lystopad Jul 20, 2026

Choose a reason for hiding this comment

Uh oh!

bloxster Jul 20, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

bloxster commented Jul 20, 2026 •

edited

Loading