docs: May 2026 w19 maintenance — stale flags, broken links, accuracy fixes#21018
Open
bloxster wants to merge 9 commits intorelease/3.4from
Open
docs: May 2026 w19 maintenance — stale flags, broken links, accuracy fixes#21018bloxster wants to merge 9 commits intorelease/3.4from
bloxster wants to merge 9 commits intorelease/3.4from
Conversation
…fixes **Stale flags removed (configuring-erigon/index.mdx):** - --snap.keepblocks: removed in #4924 (no longer in binary) - --snap.stop: removed in #11403 - --snap.state.stop: removed in #11403 - --sync.parallel-state-flushing: removed in #11685 **Broken GitHub blob links fixed (versioned_docs/version-v3.3):** - cmd/rpcdaemon/README → README.md (erigon.md, rpc-daemon.md ×2) - cmd/downloader/readme → readme.md (downloader.md) **Content accuracy fixes:** - sync-modes.md: "three prune modes" → "four" (full/minimal/blocks/archive); updated frontmatter description to match - how-to-run-an-ethereum-node/index.md: "a Ethereum" → "an Ethereum"; Flag explanation section was describing Gnosis/Chiado — corrected to Ethereum mainnet; --http.addr="0.0.0.0" → --http.addr=0.0.0.0 (exec-form passes quotes through literally) - versioned_docs/version-v3.3/downloader.md: --downloader.disable.ipv4 said "Turns off ipv6" — corrected to ipv4 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
bloxster
requested review from
AskAlexSharov,
Giulio2002,
anacrolix,
awskii,
canepat,
domiwei,
lupin012,
mh0lt,
mriccobene,
sudeepdino008,
taratorio and
yperbasis
as code owners
…/3.4) Flag is defined in node/cli/flags.go and registered in DefaultFlags on release/3.4 — incorrectly removed in previous commit. Only the three snap.* flags were truly absent from the binary. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
bloxster
requested review from
Copilot
and removed request for
Giulio2002,
anacrolix,
awskii,
canepat,
domiwei,
lupin012,
mh0lt,
mriccobene,
sudeepdino008 and
taratorio
Contributor
There was a problem hiding this comment.
Pull request overview
Docs maintenance pass for week 19 (May 2026) to keep the Docusaurus docs aligned with release/3.4, removing stale CLI flags, fixing broken GitHub links, and correcting a few content inaccuracies.
Changes:
- Removed documentation for CLI flags that no longer exist (
--snap.keepblocks,--snap.stop,--snap.state.stop). - Fixed broken GitHub blob links that pointed to
README/readmewithout the.mdsuffix. - Corrected sync/prune mode counts and a few wording/flag examples (e.g., docker-compose
--http.addrquoting, ipv4/ipv6 flag description).
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| docs/site/versioned_docs/version-v3.3/interacting-with-erigon/erigon.md | Fixes a GitHub link to point to README.md anchor correctly. |
| docs/site/versioned_docs/version-v3.3/fundamentals/modules/rpc-daemon.md | Fixes GitHub links to cmd/rpcdaemon/README.md and anchors. |
| docs/site/versioned_docs/version-v3.3/fundamentals/modules/downloader.md | Fixes downloader README link target and corrects --downloader.disable.ipv4 description. |
| docs/site/docs/get-started/easy-nodes/how-to-run-an-ethereum-node/index.md | Fixes grammar, corrects mainnet flag explanation, and removes YAML exec-form quoting for --http.addr. |
| docs/site/docs/fundamentals/sync-modes.md | Updates frontmatter + text to reflect four prune modes (incl. blocks). |
| docs/site/docs/fundamentals/configuring-erigon/index.mdx | Removes stale snapshot-related flags from the configuration reference. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Spell: - "Lighhouse" → "Lighthouse" in external-consensus-client-as-validator.md (v3.4 + v3.3) - "Lightouse" → "Lighthouse" + "your is" → "your node is" in gnosis-with-an-external-cl.md (v3.4 + v3.3) Syntax: - "a Ethereum" → "an Ethereum" in gnosis-with-an-external-cl.md (v3.4 + v3.3) - "a Ethereum" → "an Ethereum" in how-to-run-an-ethereum-node/index.md (v3.3) - "a archive" → "an archive" in basic-usage.mdx + basic-usage.md (v3.4 + v3.3) - Add missing \ line continuation in basic-usage (v3.4 + v3.3), external-consensus-client-as-validator (v3.4 + v3.3), multiple-instances (v3.3) Semantic: - Go 1.24+ → Go 1.25+ in contributing.md (matches go.mod) - "three prune modes" → "four prune modes" in versioned sync-modes.md (v3.3) - Fix sync-modes.md v3.3 frontmatter description to include "blocks" mode Branding: - "Github" → "GitHub" in versioned contributing.md (v3.3) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Link text showed ./cmd/downloader/README.md but target is readme.md — align them. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
…uracy Agent-Logs-Url: https://github.com/erigontech/erigon/sessions/8c1f2179-b80e-4aea-afd3-7a7b51778b66 Co-authored-by: bloxster <40316187+bloxster@users.noreply.github.com>
Standardize the flag description in basic-usage, easy-nodes, and configuring-erigon (both current and v3.3 versioned docs) with shared-machine context and the Inf option. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
yperbasis
requested changes
May 7, 2026
Member
yperbasis
left a comment
yperbasis
left a comment
There was a problem hiding this comment.
Summary
Docs maintenance pass covering broken GitHub links, grammar/spelling, stale flag info, and updated --torrent.download.rate descriptions across 18 files. CI is green. Most changes are accurate and helpful — but there's one factual regression in the flag reference that was already flagged by Copilot and isn't actually fixed.
Verified correct
| Change | Verified against |
|---|---|
Go 1.24+ → Go 1.25+ in contributing.md |
go.mod says go 1.25.7 |
three prune modes → four (full/blocks/minimal/archive) |
node/cli/flags.go PruneModeFlag and db/kv/prune/storage_mode.go |
--downloader.disable.ipv4 "Turns off ipv6" → "ipv4" |
cmd/utils/flags.go:771 DisableIPV4 Usage matches |
README → README.md, readme → readme.md link targets |
cmd/rpcdaemon/README.md (mixed case) and cmd/downloader/readme.md (lowercase) both exist |
--http.addr="0.0.0.0" → --http.addr=0.0.0.0 in Docker Compose |
Correct — exec-form YAML list passes quotes through literally |
| Grammar/spelling fixes ("a Ethereum" → "an Ethereum", "Lighhouse"/"Lightouse" → "Lighthouse", "your is" → "your node is") | All clearly correct |
--torrent.download.rate description (512mb default, cap not guarantee, Inf option) |
Matches cmd/utils/flags.go |
Issue: snap.* flag descriptions are factually wrong
In docs/site/docs/fundamentals/configuring-erigon/index.mdx the new wording is:
* `--snap.keepblocks`: Advanced/debug snapshot option to keep block data while working with snapshots. Intended mainly for troubleshooting or workaround scenarios.
* `--snap.stop value`: Advanced/debug snapshot option to stop snapshot processing at a specified block or stage boundary.
* `--snap.state.stop value`: Advanced/debug snapshot option to stop state snapshot processing at a specified block or stage boundary.
Three problems, verifying against cmd/utils/flags.go:690-700 on release/3.4:
valuesuffix is wrong. All three arecli.BoolFlag— they don't take an argument.--snap.stop valueand--snap.state.stop valuefalsely imply they accept a parameter.- "at a specified block or stage boundary" is fabricated. The actual flag usage is: "Workaround to stop producing new snapshots, if you meet some snapshots-related critical bug. It will stop move historical data from DB to new immutable snapshots..." — it's a global on/off, not a boundary.
Default: falselines were dropped for these three (other booleans in the section keep them).
The pre-PR text (Stops generating new snapshots / Stops generating new state files / Default: false) was terse but accurate; the new text is more confident but less correct.
Copilot's reviewer caught a related concern (whether the flags should be documented at all) but the author kept them documented and replaced the descriptions with these fabricated ones — that change went unaddressed in the back-and-forth.
Suggested fix — keep close to the actual Usage strings:
* `--snap.keepblocks`: Workaround/debug — keeps ancient blocks in the DB instead of moving them into snapshots.
* Default: `false`
* `--snap.stop`: Workaround for snapshot-related bugs — stops producing new snapshot files (DB will grow as a result).
* Default: `false`
* `--snap.state.stop`: Workaround for state-related bugs — stops producing new state files (DB will grow as a result).
* Default: `false`
Minor
- v3.4 link text mismatch missed.
docs/site/docs/fundamentals/modules/downloader.mdxstill shows link text[./cmd/downloader/README.md]while the URL goes toreadme.md. The same mismatch was fixed for v3.3 but not for the current docs (the file is.mdx, which is why it wasn't in the file list). gnosis-with-an-external-cl.mdopening sentence ("you can also run an Ethereum node as an Execution Layer") — pre-existing copy-paste from the Ethereum page; the PR fixes the grammar but the page is about Gnosis (--chain=gnosis). Worth correcting in this maintenance pass while the file is being touched.multiple-instances.md\continuation — the snippet (--db.growth.step=32MB \/--db.size.limit=512MB) reads as a flag-fragment example rather than a literal command. The continuation isn't wrong but isn't strictly needed either.
Recommendation
Fix the snap.* flag descriptions before merge — that's a documentation regression where readers would learn something false. The other items are nice-to-haves; the rest of the PR is solid.
Collaborator
Author
|
@copilot fix the PR acc. to yperbasis comment |
… intro Agent-Logs-Url: https://github.com/erigontech/erigon/sessions/72019341-9728-4e78-8f3a-560c2220dd6f Co-authored-by: bloxster <40316187+bloxster@users.noreply.github.com>
Contributor
Fixed in 92594b8:
|
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.
Summary
Addresses findings from the w19 weekly docs full check against
release/3.4.Changes
Broken GitHub blob links fixed —
versioned_docs/version-v3.3/interacting-with-erigon/erigon.mdREADME→README.mdfundamentals/modules/rpc-daemon.mdREADME→README.md(×2)fundamentals/modules/downloader.mdreadme→readme.mdContent & language fixes
docs/fundamentals/sync-modes.mdversioned_docs/version-v3.3/fundamentals/sync-modes.mddocs/about/contributing.mdgo.mod)docs/get-started/easy-nodes/how-to-run-an-ethereum-node/index.md--http.addr="0.0.0.0"→--http.addr=0.0.0.0docs/.../gnosis-with-an-external-cl.md(v3.4 + v3.3)versioned_docs/version-v3.3/.../how-to-run-an-ethereum-node/index.mddocs/fundamentals/basic-usage.mdx(v3.4 + v3.3)\line continuation addeddocs/staking/external-consensus-client-as-validator.md(v3.4 + v3.3)\line continuation addedversioned_docs/version-v3.3/fundamentals/multiple-instances.md\line continuation addedversioned_docs/version-v3.3/fundamentals/modules/downloader.md--downloader.disable.ipv4described as "Turns off ipv6" — corrected to ipv4docs/staking/external-consensus-client-as-validator.md(v3.4 + v3.3)docs/.../gnosis-with-an-external-cl.md(v3.4 + v3.3)versioned_docs/version-v3.3/about/contributing.mddocs/fundamentals/basic-usage.mdx+ v3.3,docs/get-started/easy-nodes/.../index.md+ v3.3,docs/fundamentals/configuring-erigon/index.mdx+ v3.3--torrent.download.ratedescription unified across all 6 files: correct default (512mb), shared-machine note, andInfoptionAfter this merges, a follow-up PR will cherry-pick to
mainon top of #21013.🤖 Generated with Claude Code