From 6ceb7069d6b9710a3ae55d3a099c6ea1fe4a9b26 Mon Sep 17 00:00:00 2001
From: Sam Wilson <sam@binarycake.ca>
Date: Fri, 6 Feb 2026 12:59:25 -0500
Subject: [PATCH 1/2] chore: update style guidelines

---
 CONTRIBUTING.md | 70 ++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 67 insertions(+), 3 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 66f9808075..c770f9ebda 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -21,15 +21,79 @@ This specification aims to be:
 2. **Complete** - Capture the entirety of _consensus critical_ parts of Ethereum.
 3. **Accessible** - Prioritize readability, clarity, and plain language over performance and brevity.
 
-### Spelling and Naming
+### Style
+
+#### Spelling and Naming
 
 - Attempt to use descriptive English words (or _very common_ abbreviations) in documentation and identifiers.
-- Avoid using EIP numbers in identifiers.
+- Avoid using EIP numbers in identifiers, and prefer descriptive text instead (eg. `FeeMarketTransaction` instead of `Eip1559Transaction`).
 - If necessary, there is a custom dictionary `whitelist.txt`.
 
+#### Comments
+
+- Don't repeat what is obvious from the code.
+- <details>
+    <summary><em>(expand)</em> Consider how future changes will interleave with yours, especially when creating sementic blocks.</summary>
+
+    <br>Consider:
+    <table valign="top">
+
+    <tr valign="top">
+    <th>Fork T</th>
+    <th>Fork T+1</th>
+    </tr>
+
+    <tr valign="top">
+
+    <td>
+
+    <!--
+        Note that the trailing whitespace is necessary to move the copy button
+        in the github UI over so it doesn't obscure the text.
+    -->
+
+    ```python
+    # EIP-1234: The dingus is the rate of fleep      
+    dingus = a + b
+    dingus += c ^ d
+    dingus /= fleep(e)
+    ```
+
+    </td>
+
+    <td>
+
+    ```python
+    # EIP-1234: The dingus is the rate of fleep      
+    dingus = a + b
+
+    # EIP-4567: Frobulate the dingus
+    dingus = frobulate(dingus)
+
+    dingus += c ^ d        # <-
+    dingus /= fleep(e)     # <-
+    ```
+
+    </td>
+
+    </tr>
+
+    </table>
+
+    The marked lines (`<-`) are now incorrectly attributed to EIP-4567 in Fork+1. Instead, omit the EIP identifier in the comments, and describe the changes introduced by the EIP in the function's docstrings. The rendered diffs will make it pretty obvious what's changed.
+  </details>
+
+#### Docstrings
+
+- Don't include the function's signature.
+- Format using markdown.
+- Don't begin with an article ("the"/"a") or a pronoun ("it", "they", etc.).
+- Write in complete sentences, providing background and context for the associated code.
+- Link to relevant standards/EIPs.
+
 ### Changes across various Forks
 
-Many contributions require changes across multiple forks, organized under `src/ethereum/*`. When making such changes, please ensure that differences between the forks are minimal and consist only of necessary differences. This will help with getting cleaner [diff outputs](https://ethereum.github.io/execution-specs/diffs/index.html).
+Many contributions require changes across multiple forks, organized under `src/ethereum/forks/*`. When making such changes, please ensure that differences between the forks are minimal and consist only of necessary differences. This will help with getting cleaner [diff outputs](https://ethereum.github.io/execution-specs/diffs/index.html).
 
 When creating pull requests affecting multiple forks, we recommended submitting your PR in two steps:
 

From 8236a0ab6e04b97ceb73c42d3b2edd321f89cb5c Mon Sep 17 00:00:00 2001
From: Sam Wilson <57262657+SamWilsn@users.noreply.github.com>
Date: Wed, 11 Feb 2026 14:06:21 -0500
Subject: [PATCH 2/2] Apply suggestion from @fselmo

Co-authored-by: felipe <fselmo2@gmail.com>
---
 CONTRIBUTING.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c770f9ebda..bf183b8bce 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -33,7 +33,7 @@ This specification aims to be:
 
 - Don't repeat what is obvious from the code.
 - <details>
-    <summary><em>(expand)</em> Consider how future changes will interleave with yours, especially when creating sementic blocks.</summary>
+    <summary><em>(expand)</em> Consider how future changes will interleave with yours, especially when creating semantic blocks.</summary>
 
     <br>Consider:
     <table valign="top">