Skip to content

docs: forward-port #21687 to main (v3.5 flag updates + Fundamentals docs)#21765

Merged
bloxster merged 3 commits into
mainfrom
docs/port-21687-to-main
Jun 12, 2026
Merged

docs: forward-port #21687 to main (v3.5 flag updates + Fundamentals docs)#21765
bloxster merged 3 commits into
mainfrom
docs/port-21687-to-main

Conversation

@bloxster

@bloxster bloxster commented Jun 12, 2026

Copy link
Copy Markdown
Collaborator

Forward-ports the docs changes merged to release/3.5 in #21687 onto main.

Verified against origin/main source per the dual-commit rule — all documented flags/defaults exist on main: snap.chaintoml-url, snap.p2p-manifest, the seven exec.* flags, EXEC3_PARALLEL=true, and exec.workers Value NumCPU()/2 (same "half" --help text, so the doc's effective-default note applies identically).

Includes:

  • New Snapshots Management page (seg du) with real mainnet-archive output
  • EIP-8252 retention-window breaking-change note in pruning-modes.md
  • CLI Reference: --snap.chaintoml-url, --snap.p2p-manifest, and the --exec.* flags (serial / no-prune / batched-io / state-cache), with the --exec.workers effective-default clarification
  • CLI Reference flattened (configuring-erigon/index.mdx → configuring-erigon.mdx; /fundamentals/configuring-erigon URL unchanged)
  • NAT moved to a top-level page; old URL preserved via @docusaurus/plugin-client-redirects
  • TLS Authentication cert-filename typo fix; Fundamentals sidebar reorder; mobile theme-color
  • llms.txt / llms-full.txt regenerated; build passes onBrokenLinks: 'throw'

🤖 Generated with Claude Code

@bloxster @claude
docs: forward-port #21687 to main (v3.5 flag updates + Fundamentals d…
1ae3f8a 
…ocs)

Ports the docs changes merged to release/3.5 in #21687 onto main. Verified
against origin/main source (per the dual-commit rule): all documented flags
and defaults exist on main — snap.chaintoml-url, snap.p2p-manifest, the seven
exec.* flags, EXEC3_PARALLEL=true, exec.workers Value=NumCPU()/2.

Includes: new Snapshots Management page (real mainnet-archive seg du output);
EIP-8252 retention-window note in pruning-modes.md; new/updated flags in the
CLI Reference (--snap.chaintoml-url, --snap.p2p-manifest, --exec.* incl.
serial/no-prune/batched-io/state-cache); CLI Reference flattened
(configuring-erigon/index.mdx -> configuring-erigon.mdx, URL unchanged); NAT
moved to a top-level page with a @docusaurus/plugin-client-redirects redirect
from the old URL; TLS cert filename typo fix; Fundamentals sidebar reorder;
mobile theme-color. llms.txt/llms-full.txt regenerated. Build passes
onBrokenLinks.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@bloxster bloxster added the docs label Jun 12, 2026
@bloxster bloxster requested a review from Copilot June 12, 2026 11:29
Copilot AI reviewed Jun 12, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Forward-ports documentation updates from release/3.5 to main, aligning Fundamentals + CLI reference docs with newer snapshot-management tooling, pruning semantics (EIP-8252 retention window), and additional v3.5-related flags/behavior.

Changes:

  • Adds a new Snapshots Management Fundamentals page documenting erigon seg du output, JSON schema, and v3.5 snapshot upgrade implications.
  • Updates Pruning Modes (v3.5 breaking-change note) and expands CLI Reference with snapshot-discovery flags (snap.*) and execution tuning flags (exec.*), plus NAT URL relocation.
  • Restructures Fundamentals sidebar ordering, introduces a client-side redirect for the NAT page move, and regenerates llms*.txt artifacts.

Reviewed changes

Copilot reviewed 30 out of 33 changed files in this pull request and generated 1 comment.

Show a summary per file
File Description
llms.txt Updates the top-level LLM index to reflect new/reordered Fundamentals pages and moved NAT URL.
llms-full.txt Regenerates the full LLM artifact with updated docs content/order (snapshots, pruning, NAT, CLI reference, etc.).
docs/site/static/llms.txt Updates the docs-site static copy of llms.txt to match the root artifact.
docs/site/package.json Adds @docusaurus/plugin-client-redirects dependency for preserving old NAT URL.
docs/site/package-lock.json Locks the new Docusaurus redirects plugin dependency.
docs/site/docusaurus.config.ts Configures a redirect from /fundamentals/configuring-erigon/nat → /fundamentals/nat.
docs/site/docs/get-started/installation/upgrading.md Fixes snapshot subcommand spelling/paths in upgrade instructions and updates snapshot upgrade/downgrade commands.
docs/site/docs/fundamentals/web3-wallet.md Adjusts sidebar ordering.
docs/site/docs/fundamentals/tls-authentication.md Fixes RPC cert filename typos and adjusts sidebar ordering.
docs/site/docs/fundamentals/supported-networks.md Adjusts sidebar ordering.
docs/site/docs/fundamentals/snapshots-management.mdx New page documenting snapshot disk usage reporting (seg du) and upgrade considerations.
docs/site/docs/fundamentals/security.md Adjusts sidebar ordering.
docs/site/docs/fundamentals/pruning-modes.md Adds v3.5 breaking-change note for EIP-8252 retention window; adjusts sidebar ordering.
docs/site/docs/fundamentals/performance-tricks.md Adjusts sidebar ordering.
docs/site/docs/fundamentals/otterscan.md Adjusts sidebar ordering.
docs/site/docs/fundamentals/optimizing-storage.md Adjusts sidebar ordering.
docs/site/docs/fundamentals/nat.md Moves NAT doc to a top-level Fundamentals page (sidebar reorder).
docs/site/docs/fundamentals/modules/index.mdx Reorders modules landing doc within sidebar.
docs/site/docs/fundamentals/modules/category.json Repositions the Modules category in Fundamentals sidebar.
docs/site/docs/fundamentals/mcp.mdx Adjusts sidebar ordering.
docs/site/docs/fundamentals/logs.md Adjusts sidebar ordering.
docs/site/docs/fundamentals/layer-2-networks.md Adjusts sidebar ordering.
docs/site/docs/fundamentals/jwt.md Adjusts sidebar ordering.
docs/site/docs/fundamentals/index.mdx Adjusts Fundamentals landing position in sidebar.
docs/site/docs/fundamentals/docker-compose.md Adjusts sidebar ordering.
docs/site/docs/fundamentals/default-ports.md Adjusts sidebar ordering.
docs/site/docs/fundamentals/database.md Adjusts sidebar ordering.
docs/site/docs/fundamentals/creating-a-dashboard.md Adjusts sidebar ordering.
docs/site/docs/fundamentals/configuring-erigon/category.json Removes the old CLI Reference category file due to CLI reference flattening.
docs/site/docs/fundamentals/configuring-erigon.mdx Expands CLI reference with snap.* and exec.* flags; updates NAT link target; removes stray editorial line.
docs/site/docs/fundamentals/caplin.md Adjusts sidebar ordering.
docs/site/docs/fundamentals/architecture.md Fixes Mermaid flowchart edge label quoting; adjusts sidebar ordering.
Files not reviewed (1)
  • docs/site/package-lock.json: Generated file

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

Comment thread docs/site/docs/get-started/installation/upgrading.md Outdated
@claude
docs: warn that snapshots reset is destructive (Copilot review)
f1d691b 
The upgrading guide described `erigon snapshots reset` as reusing existing
data, but per main's reset.Reset.Run() (db/datadir/reset/reset.go) it deletes
chaindata/ (plus Heimdall/Polygon-bridge DBs) and resets snapshots/ to the
preverified set, then re-downloads (`--local` defaults to true). Correct the
description, fix the misleading "reuse existing data" step, and add a data-loss
warning. (Pre-existing text; fixing here in the port and via a matching
release/3.5 PR so both branches stay in sync.)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@bloxster bloxster mentioned this pull request Jun 12, 2026
Merged
@claude
docs: clarify snapshots reset keeps preverified snapshots (Copilot …
cf3c8a2 
…review)

Per decideRemove() in db/datadir/reset/reset.go, reset keeps preverified
snapshot files already on disk and only removes unknown/locally generated
files and mismatched torrents; the next start downloads only missing or
incorrect snapshots (not a full re-download). Reword the description and
warning accordingly. chaindata/ is still deleted unconditionally.
Mirrors the same fix on the release/3.5 PR.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@bloxster bloxster added this pull request to the merge queue Jun 12, 2026
bloxster pushed a commit that referenced this pull request Jun 12, 2026
@claude
docs: warn that snapshots reset is destructive (upgrading guide)
afb76dc 
The Upgrading guide described `erigon snapshots reset` as reusing existing
data, but per `reset.Reset.Run()` (db/datadir/reset/reset.go) it deletes
chaindata/ (plus Heimdall/Polygon-bridge DBs) and removes non-preverified /
mismatched snapshot files, keeping preverified snapshots already on disk;
the next start downloads only missing or incorrect snapshots. Correct the
description, fix the misleading "reuse existing data" step, and add a
data-loss warning. (Flagged by Copilot; matches the same fix on the main
port #21765.)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Merged via the queue into main with commit a8eeb45 Jun 12, 2026
20 checks passed
@bloxster bloxster deleted the docs/port-21687-to-main branch June 12, 2026 17:12
@bloxster bloxster mentioned this pull request Jun 12, 2026
Merged
AskAlexSharov pushed a commit that referenced this pull request Jun 13, 2026
@bloxster @claude
docs: warn that snapshots reset is destructive (upgrading guide) (#…
7ffe2eb 
…21766)

The Upgrading guide described `erigon snapshots reset` as reusing
existing data, but per `reset.Reset.Run()` (`db/datadir/reset/reset.go`)
it **deletes `chaindata/`** (plus the Heimdall / Polygon-bridge DBs) and
resets `snapshots/` to the preverified set, then re-downloads (`--local`
defaults to `true`).

Corrects the `reset` description, removes the misleading "reuse existing
data" step, and adds a data-loss warning recommending
`update-to-new-ver-format` when you want to keep your data.

Flagged by Copilot on #21765 (the main forward-port); applying the same
fix here so release/3.5 and main stay in sync. Build passes
`onBrokenLinks` / `onBrokenAnchors`; `llms.txt` / `llms-full.txt`
regenerated.

🤖 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>
pull Bot pushed a commit to Dustin4444/erigon that referenced this pull request Jun 13, 2026
@bloxster @claude
docs: cross-link CLI Reference sections to their dedicated pages (eri…
50a6302 
…gontech#21772)

Main counterpart of erigontech#21763 (which added the same cross-links on
release/3.5). Now that erigontech#21765 (the erigontech#21687 forward-port) has merged, the
flattened CLI Reference page and its link targets exist on `main`, so
this applies cleanly.

Adds one cross-link per section of the **CLI Reference**
(`configuring-erigon`) to its dedicated page — in the section explainer
where possible, or on the most relevant flag. One link per target, no
duplicates of the links already present (nat / supported-networks /
pruning-modes / eth_getProof).

**Explainer links:** Database, Snapshots Management, TxPool, Default
Ports, Interacting with Erigon (RPC), MCP, Logs, Sentry, Downloader,
Caplin, Shutter Network, Docker Compose.
**Targeted flag links:** JWT (on `--authrpc.jwtsecret`), Creating a
dashboard (on `--metrics`).

Build passes the `onBrokenLinks: 'throw'` check; `llms.txt` /
`llms-full.txt` regenerated.

🤖 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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

@yperbasis yperbasis yperbasis approved these changes

@AskAlexSharov AskAlexSharov Awaiting requested review from AskAlexSharov AskAlexSharov is a code owner

Assignees

No one assigned

Labels

docs

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@bloxster @yperbasis