Skip to content

rust: keep shared reth update guidance in UPDATING-RETH - #24132

Merged
sebastianst merged 4 commits into
developfrom
seb/reth-update-docs-dedup
Nov 16, 2026
Merged

sebastianst merged 4 commits into
developfrom
seb/reth-update-docs-dedup

Conversation

@sebastianst

@sebastianst sebastianst commented Nov 13, 2026 •

Copy link
Copy Markdown
Member

Makes rust/UPDATING-RETH.md the entry point for guidance that both the reth updater and the reviewer need, with two topics split into their own files under rust/. The review guide, the reth-update-reviewer agent and the update-reth skill now keep only what one of them needs, and point at the shared docs for the rest.

  • rust/UPSTREAM-ASSUMPTIONS.md (new): "The precondition question" moves there from docs/ai/reth-update-review.md, together with its list of upstream assumptions OP breaks, re-read against revm 43. Its wording is now neutral between updater and reviewer. UPDATING-RETH step 7 keeps the question with a short deposit example and sends the updater there for any consensus-adjacent change, not only for validation or gas. The review guide keeps a stub link.

  • rust/RETH-CARRIED-PATCHES.md (new): the fork's carried patches move out of UPDATING-RETH into a table with each fix's first upstream release, refreshed (v2.10.0 contains fix(trie): tighten iterator seek boundary paradigmxyz/reth#28264 and #28253, v2.11.0 contains #28266), plus carry notes only where needed. Step 2 links to it.
    Both splits are from @aakoshh's review: the update procedure stays short, and the fork state that changes with every pick has its own file.

  • Restatements in the review guide replaced with pointers:

    • Its fork-pin audit points at UPDATING-RETH step 2. It keeps a check, which the agent's version had, that the new fork pin builds on the selected target, comparing against the target tag rather than a merge base with main.
    • Risk F points at step 4. The Scope section's note on git-source drift points at step 5, and risk E's rigor note at step 7.
  • Restatements in the agent and the skill replaced with pointers:

    • The agent's own copy of the review process (steps 0–3) is folded into the review guide, and its forward-sweep paragraph is shortened.
    • The skill's fork prep mechanics and merge gate point at "The reth fork" and "Pinning a fork change".
  • docs/ai/rust-dev.md: two tips repeated step 7 and the upstream-churn section.

    • The compile-loop tip is cut down to its agent-only part.
    • The vendoring tip is deleted, and its caveat about the upstream "stale" label moves into the churn section.
  • Forward sweep: step 5 and the pick bar no longer read as addressed to an AI assistant (from @aakoshh's review of rust: make the reth forward sweep reviewable #24106).

Follow-up to #24106.

🤖 Co-created with Claude Opus 5.5

@sebastianst
sebastianst requested a review from a team as a code owner November 13, 2026 13:37
Base automatically changed from seb/reth-forward-sweep-guide to develop November 13, 2026 14:25
sebastianst and others added 3 commits November 13, 2026 15:25
The precondition question is applied by both the updater (step 7) and the
reviewer, so it moves into the update guide. The review guide, the reviewer
agent, the update-reth skill and the Rust agent tips drop their restatements
of the pin audit, the downstream-version rules, the fork prep and the merge
gate, and point at the guide instead.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@sebastianst
sebastianst force-pushed the seb/reth-update-docs-dedup branch from 5ff9fba to 273ee9a Compare November 13, 2026 14:26

@aakoshh aakoshh 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.

Moving the precondition question out of docs/ai/ is the right direction: a human reviewer needs it as much as an agent, and one neutral source beats three copies. But UPDATING-RETH.md is turning into one document for every audience. This PR takes it from 616 to 779 lines, and the procedure alone is already 270. I'd move two kinds of content that change faster than the procedure into their own files.

1. The precondition question → rust/UPSTREAM-PRECONDITIONS.md. Here it's about 100 lines of handler internals between the post-merge steps and the upstream-churn section. It already reads stale: it says "as of revm 42", while this PR's lockfile is on revm 43.0.3. The new file would take the tell, all six preconditions and "How to check one", and UPDATING-RETH.md and the review guide would both link to it. Step 7 would only need the question and a plain example of what to look for, for instance:

For any consensus-adjacent change, ask what upstream assumes when it calls the change safe, and whether that assumption holds on OP. Upstream often drops a check because "earlier validation already rules this out". But OP skips some of that validation for deposits, since L1 has already checked them, so a check upstream removes as unreachable can still matter for a deposit. Upstream preconditions lists where OP breaks upstream's assumptions and how to check a change.

The example only illustrates the idea, so it doesn't need updating when the list changes.

2. Carried patches → rust/RETH-CARRIED-PATCHES.md. This section has changed in #23942, #24024 and #24101 within three days, and it will change with every fork pick and bump. Each bullet mixes state (which fork PR on which branch, which release contains the fix), instructions per base, and history ("Onto v2.7.0 it conflicted in…"). It has already fallen behind: it says to carry the paradigmxyz/reth#28266 backport "until a release contains it", and that no release up to v2.9.0 contains paradigmxyz/reth#28264, but v2.11.0 and v2.10.0 now contain them. In its own file it could open with a table, one row per upstream fix, holding what the step 2 audit needs, for example:

Patch Upstream First release Fork PRs Drop when
RPC replay through the block executor paradigmxyz/reth#28266 (backport) v2.11.0 ethereum-optimism/reth#37, ethereum-optimism/reth#41 base ≥ v2.11.0
Trie iterator seek boundary paradigmxyz/reth#28264 v2.10.0 ethereum-optimism/reth#32, ethereum-optimism/reth#40 base ≥ v2.10.0
Bound eth_callBundle paradigmxyz/reth#28253 v2.10.0 ethereum-optimism/reth#44 (hand-port) base ≥ v2.10.0

Below the table, only patches that need carry instructions get a short section: how to carry it onto each kind of base, and which op-reth mirrors and tests to check. The replay backport needs that room; most of the forward fixes don't. History notes can then be deleted once the base moves past them, without editing the guide. The "Forward fixes" bullet, eight PRs with three different first releases in one paragraph, would become eight rows that the audit can drop one at a time. Step 2 would then link to the file, the same pattern as for the preconditions.

The precondition question and the fork's carried patches change faster than
the update procedure, so each gets its own file (UPSTREAM-ASSUMPTIONS.md and
RETH-CARRIED-PATCHES.md) that UPDATING-RETH, the review guide and the reviewer
agent link to. Step 7 keeps the question with a short deposit example. The
carried patches become a table with each fix's first upstream release,
refreshed: v2.10.0 contains paradigmxyz/reth#28264 and #28253, v2.11.0
contains #28266. Precondition 1 is re-read against revm 43.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@sebastianst

Copy link
Copy Markdown
Member Author

🤖 Opus 5.5 says: Both splits are done in 7c503bb.

  • rust/UPSTREAM-ASSUMPTIONS.md: the precondition question and the list of upstream assumptions OP breaks. Step 7 keeps the question with your deposit example. Precondition 1 is re-read against revm 43.0.3, and every item still holds. One addition: upstream now also skips the EIP-7825 gas-limit cap once EIP-8037 state gas is on.
  • rust/RETH-CARRIED-PATCHES.md: a table of patch, upstream PR, first release and fork PRs, with carry notes only where needed. Each first release was checked against the release tags. The replay backport's notes are split by base now that v2.11.0 contains #28266. I left out the "Drop when" column, since step 2's audit already decides drops by ancestry and patch id, so the first release is enough.

UPDATING-RETH drops from 779 to 648 lines.

@aakoshh aakoshh 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.

Thanks, this gave these technical points some much needed room to breathe 📖 👀

@aakoshh
aakoshh enabled auto-merge November 16, 2026 19:25
@aakoshh
aakoshh added this pull request to the merge queue Nov 16, 2026
@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to no response for status checks Nov 16, 2026
@sebastianst
sebastianst added this pull request to the merge queue Nov 16, 2026
Merged via the queue into develop with commit 8079cdb Nov 16, 2026
116 checks passed
@sebastianst
sebastianst deleted the seb/reth-update-docs-dedup branch November 16, 2026 20:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants