diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 66f9808075..bf183b8bce 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. +-
+ (expand) Consider how future changes will interleave with yours, especially when creating semantic blocks. + +
Consider: + + + + + + + + + + + + + + + +
Fork TFork T+1
+ + + + ```python + # EIP-1234: The dingus is the rate of fleep + dingus = a + b + dingus += c ^ d + dingus /= fleep(e) + ``` + + + + ```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) # <- + ``` + +
+ + 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. +
+ +#### 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: