AGENTS.md · prometheus/prometheus

Sections

1. PR Title Format
2. Commits
3. Release Notes Block
4. Tests
5. Library Use and API Stability
6. Performance Work
7. Code Style
8. Linking Issues
9. Scope Discipline
10. Documentation Changes
11. CI / Workflow Changes

First lines (shown under the repo's Apache-2.0 license)

# Agents Guide for Prometheus

This document captures patterns and preferences observed from maintainer reviews
of recently merged pull requests. Use it to align your contributions with what
maintainers expect.

---

## PR Title Format

Titles must follow `area: short description`, using a prefix that identifies the
subsystem. Examples from merged PRs:

```
tsdb/wlog: optimize WAL watcher reads
fix(PromQL): do not skip histogram buckets when trimming
feat(agent): fix ST append; add compliance RW sender test
chore: fix emptyStringTest issues from gocritic
ci: add statuses write permission to prombench workflow
docs: clarify that `lookback_delta` query parameter takes either a duration or number of seconds
```

Common area prefixes: `tsdb`, `tsdb/wlog`, `promql`, `discovery/<name>`, `agent`,
`alerting`, `textparse`, `ui`, `build`, `ci`, `docs`, `chore`.

For performance work, append `[PERF]` to the area segment or use the `perf(area):`
convention.

---

## Commits

- 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.
- Keep commits small and focused. Do not bundle unrelated changes in one commit.
- Sign off every commit with `git commit -s` to satisfy the DCO requirement.
- Do not include unrelated local changes in the PR.

---

## Release Notes Block

Every PR must include a `release-notes` fenced code block in the description.
If there is no user-facing change, write `NONE`:

````
```release-notes
NONE
```
````

Otherwise use one of these prefixes, matching the CHANGELOG style:

```
[FEATURE]     new capability
[ENHANCEMENT] improvement to existing behaviour
[PERF]        performance improvement
[BUGFIX]      bug fix
[SECURITY]    security fix
[CHANGE]      breaking or behavioural change
```

Example:
````
```release-notes
[BUGFIX] PromQL: Do not skip histogram buckets in queries where histogram trimming is used.
```
````

---

## Tests

- Bug fixes require a test that reproduces the bug.
- New behaviour or exported API changes require unit or e2e tests.
- Tests should attempt to mirror realistic data and/or behaviour.
- Use only exported APIs in tests where possible — this keeps tests closer to
  real library usage and simplifies review.
- Prefer adding cases to existing table-driven tests over writing new test
  functions, even if the existing test needs minor adjustments to fit the new
  case. Where it helps, convert an existing test into a table-driven test
  rather than duplicating it.
- Inline subtests in their parent test function. Extract a helper only when
  setup or behavior is genuinely reused; do not extract one-off subtests merely
  to avoid indentation.

---

## Library Use and API Stability

- Prometheus offers no stability guarantees for the Go APIs of packages that
  are part of the server (see [docs/stability.md](docs/stability.md)), and
  this repository is
  [not designed for use as a library](README.md#using-prometheus-as-a-go-library).
- Still, many projects use this repository as a library, so keep changes to
  exported Go APIs to a minimum. Before removing or changing an exported
  function, method or type, check how downstream projects such as
  [Cortex](https://github.com/cortexproject/cortex),
  [Thanos](https://github.com/thanos-io/thanos) and
  [Mimir](https://github.com/grafana/mimir) use it.
- A bug fix must fix the behaviour of Prometheus itself. A problem that is
  only reachable through Go library use, for example using a type in a way
  that no Prometheus code path does, is not a bug: do not label the change
  `[BUGFIX]`, do not call it a regression, and do not propose backports.
- Properties of a type that are not documented, such as concurrency safety,
  are not guarantees. Check the type's documentation before relying on them.

---

## Performance Work

Maintainers take performance seriously. For any PERF PR:

- Performance improvements require a benchmark that demonstrates the improvement.
- Run benchmarks before and after the change using `go test -count=6 -benchmem -bench <directory changed in PR>`
- Provide benchmark numbers in the PR body using `benchstat` output.
- If a subset of benchmark results show a regression, address this or explain why the case is not important.
- Reuse allocations in hot paths where possible (slices, buffers). 
- When reusing buffers passed to interfaces, document that callers must copy
  the contents and must not retain references.
- Link to supporting analysis (Google Doc, issue, etc.) for complex changes.

---

## Code Style

- Follow [Go Code Review Comments](https://go.dev/wiki/CodeReviewComments)
  and the formatting/style section of
  [Go: Best Practices for Production Environments](https://peter.bourgon.org/go-in-production/#formatting-and-style).
- State your assumptions.
- Interface contracts: when ownership or lifetime semantics (e.g. buffer reuse) are important,
  document it at the interface definition, not just in the implementation.
- All exposed objects must have a doc comment.
- All comments must start with a capital letter and end with a full stop.
- Run `make lint` before submitting. The project uses `golangci-lint` including
  `gocritic` rules such as `emptyStringTest` — fix linter findings rather than
  suppressing them with `//nolint` unless there is a clear false-positive.
- Use `//nolint:linter1[,linter2,...]` sparingly; prefer fixing the code.

---

## Linking Issues

Use GitHub closing keywords in the PR body so the linked issue closes
automatically on merge:

```
Fixes #18243
```

---

## Scope Discipline

- Do not include unrelated changes in a PR; make a separate PR instead.
- If a refactor is necessary to make a change, do those in separate commits.
- If a PR is large, split it into preparatory and follow-up PRs and reference
  them with "Part of #NNNN" or "Depends on #NNNN".

---