AGENTS.md

1# AGENTS
2 
3## Guidelines
4 
5- **Keep changes minimal and focused.** Only modify code directly related to the task at hand. Do not refactor unrelated code, rename existing variables or functions for style, or bundle unrelated fixes into the same commit or PR.
6- **Do not add, remove, or update dependencies** unless the task explicitly requires it.
7 
8## Pre-Commit Checklist
9 
10Before every commit, run **all** of the following checks and ensure they pass:
11 
12### 1. Formatting
13 
14Before committing, always run `gofmt` and `goimports` on all modified files:
15 
16```sh
17gofmt -w <modified files>
18goimports -w <modified files>
19```
20 
21### 2. Build All Commands
22 
23Verify that all tools compile successfully:
24 
25```sh
26make all
27```
28 
29This builds all executables under `cmd/`, including `keeper` which has special build requirements.
30 
31### 3. Tests
32 
33While iterating during development, use `-short` for faster feedback:
34 
35```sh
36go run ./build/ci.go test -short
37```
38 
39Before committing, run the full test suite **without** `-short` to ensure all tests pass, including the Ethereum execution-spec tests and all state/block test permutations:
40 
41```sh
42go run ./build/ci.go test
43```
44 
45### 4. Linting
46 
47```sh
48go run ./build/ci.go lint
49```
50 
51This runs additional style checks. Fix any issues before committing.
52 
53### 5. Generated Code
54 
55```sh
56go run ./build/ci.go check_generate
57```
58 
59Ensures that all generated files (e.g., `gen_*.go`) are up to date. If this fails, first install the required code generators by running `make devtools`, then run the appropriate `go generate` commands and include the updated files in your commit.
60 
61### 6. Dependency Hygiene
62 
63```sh
64go run ./build/ci.go check_baddeps
65```
66 
67Verifies that no forbidden dependencies have been introduced.
68 
69## What to include in commits
70 
71Do not commit binaries, whether they are produced by the main build or byproducts of investigations.
72 
73## Commit Message Format
74 
75Commit messages must be prefixed with the package(s) they modify, followed by a short lowercase description:
76 
77```
78<package(s)>: description
79```
80 
81Examples:
82- `core/vm: fix stack overflow in PUSH instruction`
83- `eth, rpc: make trace configs optional`
84- `cmd/geth: add new flag for sync mode`
85 
86Use comma-separated package names when multiple areas are affected. Keep the description concise.
87 
88## Pull Request Title Format
89 
90PR titles follow the same convention as commit messages:
91 
92```
93<list of modified paths>: description
94```
95 
96Examples:
97- `core/vm: fix stack overflow in PUSH instruction`
98- `core, eth: add arena allocator support`
99- `cmd/geth, internal/ethapi: refactor transaction args`
100- `trie/archiver: streaming subtree archival to fix OOM`
101 
102Use the top-level package paths, comma-separated if multiple areas are affected. Only mention the directories with functional changes, interface changes that trickle all over the codebase should not generate an exhaustive list. The description should be a short, lowercase summary of the change.
103