AGENTS.md

1# Agents Guide for Prometheus
2 
3This document captures patterns and preferences observed from maintainer reviews
4of recently merged pull requests. Use it to align your contributions with what
5maintainers expect.
6 
7---
8 
9## PR Title Format
10 
11Titles must follow `area: short description`, using a prefix that identifies the
12subsystem. Examples from merged PRs:
13 
14```
15tsdb/wlog: optimize WAL watcher reads
16fix(PromQL): do not skip histogram buckets when trimming
17feat(agent): fix ST append; add compliance RW sender test
18chore: fix emptyStringTest issues from gocritic
19ci: add statuses write permission to prombench workflow
20docs: clarify that `lookback_delta` query parameter takes either a duration or number of seconds
21```
22 
23Common area prefixes: `tsdb`, `tsdb/wlog`, `promql`, `discovery/<name>`, `agent`,
24`alerting`, `textparse`, `ui`, `build`, `ci`, `docs`, `chore`.
25 
26For performance work, append `[PERF]` to the area segment or use the `perf(area):`
27convention.
28 
29---
30 
31## Commits
32 
33- Each commit must compile and pass tests independently, except when one commit adds a test to expose a bug and then the next commit fixes the bug.
34- Keep commits small and focused. Do not bundle unrelated changes in one commit.
35- Sign off every commit with `git commit -s` to satisfy the DCO requirement.
36- Do not include unrelated local changes in the PR.
37 
38---
39 
40## Release Notes Block
41 
42Every PR must include a `release-notes` fenced code block in the description.
43If there is no user-facing change, write `NONE`:
44 
45```
46```release-notes
47NONE
48```
49```
50 
51Otherwise use one of these prefixes, matching the CHANGELOG style:
52 
53```
54[FEATURE]     new capability
55[ENHANCEMENT] improvement to existing behaviour
56[PERF]        performance improvement
57[BUGFIX]      bug fix
58[SECURITY]    security fix
59[CHANGE]      breaking or behavioural change
60```
61 
62Example:
63```
64```release-notes
65[BUGFIX] PromQL: Do not skip histogram buckets in queries where histogram trimming is used.
66```
67```
68 
69---
70 
71## Tests
72 
73- Bug fixes require a test that reproduces the bug.
74- New behaviour or exported API changes require unit or e2e tests.
75- Tests should attempt to mirror realistic data and/or behaviour.
76- Use only exported APIs in tests where possible — this keeps tests closer to
77  real library usage and simplifies review.
78- Prefer adding cases to existing table-driven tests over writing new test
79  functions, even if the existing test needs minor adjustments to fit the new
80  case. Where it helps, convert an existing test into a table-driven test
81  rather than duplicating it.
82 
83---
84 
85## Performance Work
86 
87Maintainers take performance seriously. For any PERF PR:
88 
89- Performance improvements require a benchmark that demonstrates the improvement.
90- Run benchmarks before and after the change using `go test -count=6 -benchmem -bench <directory changed in PR>`
91- Provide benchmark numbers in the PR body using `benchstat` output.
92- If a subset of benchmark results show a regression, address this or explain why the case is not important.
93- Reuse allocations in hot paths where possible (slices, buffers). 
94- When reusing buffers passed to interfaces, document that callers must copy
95  the contents and must not retain references.
96- Link to supporting analysis (Google Doc, issue, etc.) for complex changes.
97 
98---
99 
100## Code Style
101 
102- Follow [Go Code Review Comments](https://go.dev/wiki/CodeReviewComments)
103  and the formatting/style section of
104  [Go: Best Practices for Production Environments](https://peter.bourgon.org/go-in-production/#formatting-and-style).
105- State your assumptions.
106- Interface contracts: when ownership or lifetime semantics (e.g. buffer reuse) are important,
107  document it at the interface definition, not just in the implementation.
108- All exposed objects must have a doc comment.
109- All comments must start with a capital letter and end with a full stop.
110- Run `make lint` before submitting. The project uses `golangci-lint` including
111  `gocritic` rules such as `emptyStringTest` — fix linter findings rather than
112  suppressing them with `//nolint` unless there is a clear false-positive.
113- Use `//nolint:linter1[,linter2,...]` sparingly; prefer fixing the code.
114 
115---
116 
117## Linking Issues
118 
119Use GitHub closing keywords in the PR body so the linked issue closes
120automatically on merge:
121 
122```
123Fixes #18243
124```
125 
126---
127 
128## Scope Discipline
129 
130- Do not include unrelated changes in a PR; make a separate PR instead.
131- If a refactor is necessary to make a change, do those in separate commits.
132- If a PR is large, split it into preparatory and follow-up PRs and reference
133  them with "Part of #NNNN" or "Depends on #NNNN".
134 
135---
136 
137## Documentation Changes
138 
139- Docs PRs are welcome for clarifying ambiguous parameter descriptions,
140  fixing Markdown formatting, and keeping the OpenAPI spec consistent with
141  the implementation.
142- When changing documented behaviour, update any relevant text in the docs/ directory.
143  Check whether the OpenAPI spec also needs updating.
144 
145---
146 
147## CI / Workflow Changes
148 
149- Workflow files need the correct GitHub token permissions declared explicitly.
150  Missing permissions (e.g. `statuses: write`) cause silent 403 failures.
151 
152---
153 
154```