From 31273c2ad3e0b74134c821368543da37d21129a1 Mon Sep 17 00:00:00 2001 From: Guillaume Ballet <3272758+gballet@users.noreply.github.com> Date: Tue, 24 Feb 2026 16:14:28 +0100 Subject: [PATCH 1/4] docs: add AGENTS.md with pre-commit guidelines for AI agents (#568) Co-authored-by: tellabg <249254436+tellabg@users.noreply.github.com> --- AGENTS.md | 85 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 85 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000000..6673780f0414 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,85 @@ +# AGENTS.md — Guidelines for AI-Assisted Contributions + +This document provides instructions for AI agents (and their operators) before committing code and creating pull requests on this repository. + +## Pre-Commit Checklist + +Before every commit, run **all** of the following checks and ensure they pass: + +### 1. Formatting + +Before committing, always run `gofmt` and `goimports` on all modified files: + +```sh +gofmt -w +goimports -w +``` + +### 2. Linting + +```sh +go run ./build/ci.go lint +``` + +This runs additional style checks. Fix any issues before committing. + +### 3. Generated Code + +```sh +go run ./build/ci.go check_generate +``` + +Ensures that all generated files (e.g., `gen_*.go`) are up to date. If this fails, run the appropriate `go generate` commands and include the updated files in your commit. + +### 4. Dependency Hygiene + +```sh +go run ./build/ci.go check_baddeps +``` + +Verifies that no forbidden dependencies have been introduced. + +### 5. Tests + +```sh +go run ./build/ci.go test +``` + +Run the full test suite. All tests must pass. + +### 6. Build All Commands + +Verify that all tools compile successfully: + +```sh +make all +``` + +This builds all executables under `cmd/`, including `keeper` which has special build requirements. + +## Pull Request Title Format + +PR titles must follow this convention: + +``` +: description +``` + +Examples: +- `core/vm: fix stack overflow in PUSH instruction` +- `core, eth: add arena allocator support` +- `cmd/geth, internal/ethapi: refactor transaction args` +- `trie/archiver: streaming subtree archival to fix OOM` + +Use the top-level package paths, comma-separated if multiple areas are affected. The description should be a short, lowercase summary of the change. + +## Summary + +Before creating a PR, confirm: + +- [ ] `gofmt` and `goimports` applied to all modified files +- [ ] `go run ./build/ci.go lint` passes +- [ ] `go run ./build/ci.go check_generate` passes +- [ ] `go run ./build/ci.go check_baddeps` passes +- [ ] `go run ./build/ci.go test` passes +- [ ] `make all` succeeds From 955d9d84947c0117614b0a2f171239d6b29cf70f Mon Sep 17 00:00:00 2001 From: Guillaume Ballet <3272758+gballet@users.noreply.github.com> Date: Tue, 24 Feb 2026 16:16:45 +0100 Subject: [PATCH 2/4] specify that we don't need to list _every_ directory in the summary line --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 6673780f0414..e2d88b9e10f5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -71,7 +71,7 @@ Examples: - `cmd/geth, internal/ethapi: refactor transaction args` - `trie/archiver: streaming subtree archival to fix OOM` -Use the top-level package paths, comma-separated if multiple areas are affected. The description should be a short, lowercase summary of the change. +Use 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. ## Summary From 174cd283aa1fd93e47c5ca2883aa875a3416c0c2 Mon Sep 17 00:00:00 2001 From: lightclient Date: Wed, 25 Feb 2026 04:32:01 +0000 Subject: [PATCH 3/4] agents: few tweaks --- AGENTS.md | 66 ++++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 46 insertions(+), 20 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index e2d88b9e10f5..3a46927ce9f3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,6 +2,11 @@ This document provides instructions for AI agents (and their operators) before committing code and creating pull requests on this repository. +## General Guidelines + +- **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. +- **Do not add, remove, or update dependencies** unless the task explicitly requires it. + ## Pre-Commit Checklist Before every commit, run **all** of the following checks and ensure they pass: @@ -15,51 +20,72 @@ gofmt -w goimports -w ``` -### 2. Linting +### 2. Build All Commands + +Verify that all tools compile successfully: ```sh -go run ./build/ci.go lint +make all ``` -This runs additional style checks. Fix any issues before committing. +This builds all executables under `cmd/`, including `keeper` which has special build requirements. -### 3. Generated Code +### 3. Tests + +While iterating during development, use `-short` for faster feedback: ```sh -go run ./build/ci.go check_generate +go run ./build/ci.go test -short ``` -Ensures that all generated files (e.g., `gen_*.go`) are up to date. If this fails, run the appropriate `go generate` commands and include the updated files in your commit. +Before 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: -### 4. Dependency Hygiene +```sh +go run ./build/ci.go test +``` + +### 4. Linting ```sh -go run ./build/ci.go check_baddeps +go run ./build/ci.go lint ``` -Verifies that no forbidden dependencies have been introduced. +This runs additional style checks. Fix any issues before committing. -### 5. Tests +### 5. Generated Code ```sh -go run ./build/ci.go test +go run ./build/ci.go check_generate ``` -Run the full test suite. All tests must pass. +Ensures 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. -### 6. Build All Commands - -Verify that all tools compile successfully: +### 6. Dependency Hygiene ```sh -make all +go run ./build/ci.go check_baddeps ``` -This builds all executables under `cmd/`, including `keeper` which has special build requirements. +Verifies that no forbidden dependencies have been introduced. + +## Commit Message Format + +Commit messages must be prefixed with the package(s) they modify, followed by a short lowercase description: + +``` +: description +``` + +Examples: +- `core/vm: fix stack overflow in PUSH instruction` +- `eth, rpc: make trace configs optional` +- `cmd/geth: add new flag for sync mode` + +Use comma-separated package names when multiple areas are affected. Keep the description concise. ## Pull Request Title Format -PR titles must follow this convention: +PR titles follow the same convention as commit messages: ``` : description @@ -78,8 +104,8 @@ Use the top-level package paths, comma-separated if multiple areas are affected. Before creating a PR, confirm: - [ ] `gofmt` and `goimports` applied to all modified files +- [ ] `make all` succeeds +- [ ] `go run ./build/ci.go test` passes - [ ] `go run ./build/ci.go lint` passes - [ ] `go run ./build/ci.go check_generate` passes - [ ] `go run ./build/ci.go check_baddeps` passes -- [ ] `go run ./build/ci.go test` passes -- [ ] `make all` succeeds From 8bc104f85be13aa20ee275a4a96834049df23a44 Mon Sep 17 00:00:00 2001 From: lightclient Date: Wed, 25 Feb 2026 04:49:21 +0000 Subject: [PATCH 4/4] agents: more tweaks --- AGENTS.md | 17 ++--------------- 1 file changed, 2 insertions(+), 15 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 3a46927ce9f3..33b31eb632e2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,8 +1,6 @@ -# AGENTS.md — Guidelines for AI-Assisted Contributions +# AGENTS -This document provides instructions for AI agents (and their operators) before committing code and creating pull requests on this repository. - -## General Guidelines +## Guidelines - **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. - **Do not add, remove, or update dependencies** unless the task explicitly requires it. @@ -98,14 +96,3 @@ Examples: - `trie/archiver: streaming subtree archival to fix OOM` Use 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. - -## Summary - -Before creating a PR, confirm: - -- [ ] `gofmt` and `goimports` applied to all modified files -- [ ] `make all` succeeds -- [ ] `go run ./build/ci.go test` passes -- [ ] `go run ./build/ci.go lint` passes -- [ ] `go run ./build/ci.go check_generate` passes -- [ ] `go run ./build/ci.go check_baddeps` passes