From 67ad3d1bd60ff70c03a03bebd4411e92a9e675a9 Mon Sep 17 00:00:00 2001 From: bool Date: Thu, 10 Sep 2026 22:03:25 +0000 Subject: [PATCH] *: add AGENTS.md for coding agents --- AGENTS.md | 119 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 119 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..a651930cb --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,119 @@ +# AGENTS.md + +Guidance for coding agents working in this repository. + +## Project overview + +etcd is a distributed, strongly-consistent key-value store built on the Raft +consensus algorithm. + +This repository is a mirror of [etcd-io/etcd](https://github.com/etcd-io/etcd) +hosted under the `sourcegraph-testing` organization and used to exercise tooling +and automation. Upstream is the source of truth. + +- Module path: `go.etcd.io/etcd/v3` +- Go version: `go 1.14` per `go.mod`; CI builds against Go 1.13.3 and tip +- `version/version.go` reports `3.5.0-pre` — a master-series pre-release, not a + tagged version. This mirror carries no release tags. + +`go.mod` contains a `replace` directive pointing `go.uber.org/zap` at +`github.com/sourcegraph-testing/zap v1.14.1`. That is deliberate for this mirror; +do not "clean it up". + +## Repository layout + +| Directory | Role | +| --- | --- | +| `etcdserver/`, `mvcc/`, `wal/`, `lease/`, `auth/` | Core server, storage, write-ahead log, leases, auth | +| `raft/` | Raft consensus implementation | +| `etcdctl/`, `etcdmain/` | CLI client and server entrypoint | +| `client/`, `clientv3/` | Go client libraries | +| `embed/` | Embeddable etcd server package | +| `proxy/`, `contrib/` | gRPC proxy and contrib integrations | +| `integration/`, `tests/`, `functional/` | Integration, e2e, and fault-injection tests | +| `scripts/`, `hack/`, `tools/` | Build and release scripts, dev helpers | +| `Documentation/` | User and developer documentation | + +## Build + +```bash +make build +``` + +Runs `GO_BUILD_FLAGS="-v" ./build`, then sanity-checks `./bin/etcd --version` and +`./bin/etcdctl version`. The `./build` script can also be invoked directly. + +## Test + +```bash +make test +``` + +Runs `TEST_OPTS='PASSES=unit' ./test` and fails if the log contains `FAIL`, +`DATA RACE`, a timeout, or a leak. + +The `./test` script is the entry point for every test pass. Select passes with +`PASSES`; it also honours `PKG`, `TESTCASE`, `CPU`, `TIMEOUT`, and `COVERDIR`. + +```bash +PASSES='unit' ./test +PASSES='integration' ./test +PKG=./mvcc/... PASSES='unit' ./test +``` + +Available passes: `fmt`, `bom`, `dep`, `build`, `unit`, `integration`, +`functional`, `release`, `grpcproxy`, `build_cov`, `cov`. With `PASSES` unset the +default is `fmt bom dep build unit`. + +Docker-based variants exist as `make docker-test`, `make docker-test-coverage`, +and several `docker-*-test` targets covering DNS, static-IP, and gRPC-proxy +scenarios. + +## Lint and format + +There is no `.golangci.yml`. Lint runs as sub-passes of the `fmt` pass: + +```bash +PASSES='fmt' ./test +``` + +That covers `gofmt -l -s -d`, `go vet`, `revive -config ./tests/revive.toml`, +license-header and receiver-name checks, commit-title validation, `shellcheck`, +and prose checks. + +Note two traps: + +- `gofmt` is only *checked*, never applied. Run `gofmt -s -w` on files you touch. +- `staticcheck`, `unparam`, `unconvert`, `ineffassign`, `nakedret`, and shadow + vet run only when their binaries are on `PATH`, and are silently skipped + otherwise. A clean local run does not imply a clean CI run. + +## Conventions + +Code style follows the +[Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments) +wiki. + +Commit messages are mechanically validated by the `commit_title_pass` check, +which rejects any title without a `:` prefix: + +```text +{, }: + + + +