Repository navigation
rust: keep shared reth update guidance in UPDATING-RETH - #24132
Conversation
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>
5ff9fba to
273ee9a
Compare
aakoshh
left a comment
There was a problem hiding this comment.
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>
|
🤖 Opus 5.5 says: Both splits are done in 7c503bb.
UPDATING-RETH drops from 779 to 648 lines. |
aakoshh
left a comment
There was a problem hiding this comment.
Thanks, this gave these technical points some much needed room to breathe 📖 👀
Makes
rust/UPDATING-RETH.mdthe entry point for guidance that both the reth updater and the reviewer need, with two topics split into their own files underrust/. The review guide, thereth-update-revieweragent and theupdate-rethskill 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 fromdocs/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:
main.Restatements in the agent and the skill replaced with pointers:
docs/ai/rust-dev.md: two tips repeated step 7 and the upstream-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