AGENTS.md

1# AGENTS.md
2 
3Instructions for AI coding agents (Claude Code, Copilot, Cursor, etc.) working in this repository.
4 
5## Critical rules
6 
71. **Always sign off commits.** The human user must sign off commits via `git commit -s` — never
8   manually write a `Signed-off-by` trailer. The sign-off attests that the committer (the user)
9   has the right to submit the code under the project's license.
102. **Always run format and lint checks before committing.** Use `tools/local_fix_format.sh` for
11   a quick local check, or run `./ci/do_ci.sh format` inside Docker for the full CI check suite.
12   Format failures are the most common CI rejection. If running checks is impractical, warn the
13   user that formatting has not been verified.
143. **Never amend commits or force-push after a PR has received human review.** Always create new
15   commits to preserve review history.
164. **Never rebase a PR that is under review.** Use `git merge main` instead to pull in recent
17   changes. The project squash-merges, so commit count does not matter.
185. **Disclose AI usage.** When submitting PRs, include a note about AI assistance in the PR
19   description. The submitter must fully understand all code being submitted.
206. **Never commit to `main`.** Always create a new branch before committing. If switching
21   contexts or unsure which branch to use, ask the user.
227. **Always push to a personal fork.** Do not create branches in the main repo.
23 
24## Developer workflow
25 
26### 1. Before starting work
27 
28Read `CONTRIBUTING.md` for the full contribution process. Key points:
29- **Major features (>100 LOC or user-facing):** Open a GitHub issue first to discuss design.
30  For new extensions, read `EXTENSION_POLICY.md`.
31- **Small patches and bug fixes:** No prior communication needed.
32- Install git hooks: `./support/bootstrap`
33 
34### 2. Writing code
35 
36Read `STYLE.md` for the C++ coding style. After writing C++ code, run `clang-format` to fix
37formatting automatically rather than trying to hand-format:
38 
39```bash
40clang-format -i <file>
41```
42 
43Tests must:
44- Live in `test/` mirroring the `source/` structure
45- Achieve 100% coverage for new code
46- Use `StrictMock` by default, `SimulatedTimeSystem` for time, port 0 for network
47- Unit tests must be hermetic and deterministic — no real time, no randomness
48- Integration tests (in `test/integration/`) use real network on localhost
49 
50### 3. Building and testing
51 
52See `bazel/README.md` for full build documentation. Common commands:
53 
54```bash
55# Docker-based (recommended — matches CI environment)
56./ci/run_envoy_docker.sh bash                                   # interactive shell
57./ci/do_ci.sh debug //test/common/http/...                      # build + test
58./ci/do_ci.sh debug.server_only                                 # build binary only
59 
60# Local (requires local dependencies)
61bazel test -c dbg //test/common/http/...                         # run tests
62bazel build --config=clang -c opt //source/exe:envoy-static      # optimized binary
63```
64 
65Sanitizers, coverage, GDB debugging, and profiling are resource-intensive. Do **not** run
66them unless the user explicitly asks. See `bazel/README.md` and `bazel/PPROF.md`.
67 
68### 4. Format and lint checks (required before every commit)
69 
70Format failures are the most common CI rejection. Agents should produce content that conforms
71to the repo's style conventions for all file types (C++, BUILD, YAML, Markdown, shell, etc.).
72 
73**Quick local check (recommended):**
74 
75```bash
76tools/local_fix_format.sh          # uncommitted changes (default)
77tools/local_fix_format.sh -main    # changes since main
78tools/local_fix_format.sh -all     # entire repo
79```
80 
81**Individual checks:**
82 
83```bash
84bazel run //tools/code_format:check_format -- fix      # C++, BUILD, .bzl, .proto
85bazel run //tools/spelling:check_spelling_pedantic -- fix   # spelling
86./ci/do_ci.sh format                                   # full CI check (inside Docker)
87```
88 
89**Linter config files — read these to produce compliant output without running the tools:**
90 
91| Config file | What it configures |
92|-------------|--------------------|
93| `.clang-format` | C++/Proto formatting (100-col, include order, pointer alignment) |
94| `.yamllint` | YAML rules (140-col max, consistent indentation) |
95| `.flake8` | Python lint rules |
96| `rustfmt.toml` | Rust formatting (100-col, 2-space indent) |
97| `tools/spelling/spelling_dictionary.txt` | Custom word list (1700+ project terms) |
98 
99### 5. Creating the commit
100 
101Before your first commit in a session:
102 
1031. Check if the local `main` is up to date with `origin/main`:
104```bash
105   git fetch origin
106   git log main..origin/main --oneline
107```
1082. If `main` is behind, sync it:
109```bash
110   git checkout main && git pull && git checkout -
111```
1123. Create a new branch off the updated `main`:
113```bash
114   git checkout -b <descriptive-branch-name>
115```
1164. If you had uncommitted changes that conflict with the updated `main`, ask the user whether
117   to proceed on the outdated base or resolve conflicts against the new `main`.
118 
119If you're switching contexts or unsure which branch to commit to, ask the user before committing.
120 
121```bash
122git add <files>
123git commit -s    # -s adds Signed-off-by automatically; NEVER write it manually
124```
125 
126### 6. Pushing and creating a PR
127 
128**PR title format** — lower-case subsystem prefix followed by a colon:
129`docs: fix grammar error`, `router: add x-envoy-overloaded header`
130 
131**PR description template** — every PR must fill in:
132 
133```
134Commit Message: <what this PR does — used as the final squash-merge message>
135Additional Description: <context useful to reviewers>
136Risk Level: Low | Medium | High
137Testing: <what testing was done>
138Docs Changes: <description or N/A>
139Release Notes: <description or N/A>
140```
141 
142See `PULL_REQUESTS.md` for full field descriptions and optional fields (runtime guard,
143deprecation, platform-specific features).
144 
145**Release notes:** User-facing changes **must** add a release note fragment under
146`changelogs/current/`. Name the file `<area>__<short-description>.rst`.
147 
148### 7. Waiting for CI and review
149 
150- Do **not** create draft PRs if you want prompt reviews — draft PRs are not triaged.
151- To re-run failed CI tasks, add a `/retest` comment on the PR.
152- PRs with no activity for 14+ days may be closed.
153 
154### 8. Addressing review comments
155 
156- **Never amend or force-push** after a reviewer has looked at the PR. Create new commits.
157- **Never rebase.** If you need to incorporate upstream changes:
158```bash
159  git fetch origin main && git merge origin/main
160```
161- If the reviewer asked for a runtime guard, add one (see `CONTRIBUTING.md`).
162 
163### 9. After merge
164 
165The project squash-merges PRs. The "Commit Message" field in your PR description becomes the
166final commit message. Make sure it's up to date before merge.
167 
168## Understanding CI
169 
170Envoy uses a checks-based CI system. Results appear as **GitHub Check Runs** on PRs, not as
171simple workflow pass/fail statuses.
172 
173**CI pipeline:**
174 
1751. **`Envoy/Prechecks`** — fast checks: format/lint/spelling, dependency validation, docs build
1762. **`Envoy/Checks`** — heavier checks: compilation, tests, coverage, sanitizers
177 
178**Checking CI status:**
179 
180```bash
181gh pr checks &lt;PR-number&gt;
182gh run view &lt;run-id&gt; --log-failed
183```
184 
185When CI fails, check the failed check run name to determine which `do_ci.sh` target to
186reproduce locally. Format failures come from `Envoy/Prechecks`; build/test failures come
187from `Envoy/Checks`.
188 
189## Inclusive language
190 
191The following terms are **not allowed**:
192- ~~whitelist~~ -> allowlist
193- ~~blacklist~~ -> denylist / blocklist
194- ~~master~~ -> primary / main
195- ~~slave~~ -> secondary / replica
196 
197## BUILD file conventions
198 
199See `bazel/DEVELOPER.md` for full BUILD file rules. Key points:
200- Use `envoy_cc_library`, `envoy_cc_test`, `envoy_cc_mock` (not raw `cc_library`)
201- Target suffixes: `_lib`, `_test`, `_mocks`, `_interface`
202- Every `#include` must have a corresponding `deps` entry
203 
204## Updating dependencies
205 
206See `bazel/EXTERNAL_DEPS.md` and `DEPENDENCY_POLICY.md`. When updating a version:
2071. Update version, sha256, and urls in `bazel/repository_locations.bzl`
2082. Update `release_date` in `bazel/deps.yaml` to the UTC date of the new release
2093. Prefer maintainer-provided tarballs over GitHub auto-generated ones
210 
211## CI and GitHub Actions (for workflow file authors)
212 
213- In `if:` conditions, do **not** wrap expressions in `${{ }}` — the `if` field evaluates
214  expressions implicitly. Use `${{ }}` only in string contexts (`run:`, `with:`, `env:`).
215- Workflow files in `.github/workflows/` are shared across all branches (main and stable release
216  branches). Do not remove variables or inputs still referenced by stable branches.
217 
218## Key files
219 
220| File | Purpose |
221|------|---------|
222| `STYLE.md` | C++ coding style and error handling |
223| `CONTRIBUTING.md` | Contribution guidelines, deprecation, breaking changes |
224| `PULL_REQUESTS.md` | PR field descriptions |
225| `EXTENSION_POLICY.md` | Extension lifecycle and requirements |
226| `DEPENDENCY_POLICY.md` | External dependency rules |
227| `RELEASES.md` | Release schedule and backport process |
228| `SECURITY.md` | Security reporting and disclosure |
229| `REPO_LAYOUT.md` | Repository structure |
230| `bazel/README.md` | Building, testing, sanitizers, coverage |
231| `bazel/DEVELOPER.md` | BUILD file conventions |
232| `bazel/EXTERNAL_DEPS.md` | Managing external dependencies |
233| `bazel/PPROF.md` | Performance profiling |
234| `source/extensions/extensions_metadata.yaml` | Extension status and security posture |
235| `source/common/runtime/runtime_features.cc` | Runtime feature flag defaults |
236