How to contribute

This section captures the conventions used in this repository: how PRs are titled, what tests are required, how commits are reviewed, and where to find the maintainers. The authoritative external document is CONTRIBUTING.md; the project's AGENTS.md and CLAUDE.md capture the same conventions for tools.

Where to start

• low-hanging-fruit issues are tagged for new contributors. The label list is at https://github.com/prometheus/prometheus/issues?q=is%3Aissue+is%3Aopen+label%3A%22low+hanging+fruit%22.
• A prebuilt dev environment is available via https://gitpod.io/#https://github.com/prometheus/prometheus.
• Larger ideas should be discussed on the prometheus-developers Google Group or #prometheus-dev IRC/Matrix room before opening a PR. See the project's non-goals issue for areas the community deliberately avoids.

PR title format

From AGENTS.md: titles follow area: short description. The area names match the directory or subsystem.

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

For performance work, append [PERF] or use the perf(area): form.

Release notes block

Every PR description must include a fenced release-notes block. Use NONE if there is no user-visible change:

```release-notes
NONE
```

Otherwise pick one of the prefixes used in CHANGELOG.md:

[FEATURE] [ENHANCEMENT] [PERF] [BUGFIX] [SECURITY] [CHANGE]

The CHANGELOG is hand-written; release coordinators (currently Alex Greenbank, Carrie Edwards, Fiona Liao, Jan Fajerski, Jesús Vázquez, Nico Pazos, Owen Williams, and Tom Braack — see MAINTAINERS.md) curate it during the release-cut PR.

DCO and commit hygiene

• Sign every commit with git commit -s to satisfy the DCO requirement (the dco GitHub App enforces this on PRs).
• Each commit must compile and pass tests on its own — except when a commit deliberately adds a failing test reproducing a bug, immediately followed by the fix commit.
• Keep commits small and focused; a refactor needed to enable a change should be its own commit.
• Do not bundle unrelated changes in one PR.

Tests

• Bug fixes require a regression test that fails without the fix.
• New behaviour or exported APIs require unit or e2e tests.
• Where possible, drive tests through exported APIs only — this keeps tests close to library users and simplifies review.
• Performance PRs require a benchmark, plus benchstat numbers in the PR body. The standard invocation is go test -count=6 -benchmem -bench <pkg>.

See Testing for how the suites are structured.

CHANGELOG and migration docs

When changing documented behaviour, update both docs/configuration/... and the user-facing migration guide docs/migration.md. If you change an API surface, update the OpenAPI specification (web/api/v1/openapi.yaml is generated from Go via the OpenAPI builder in web/api/v1/openapi*.go).

Linking issues

Use GitHub closing keywords in the PR body so issues close automatically:

Fixes #18243

For larger work, reference siblings with Part of #NNNN or Depends on #NNNN.

Working with the maintainers

• General maintainers (see MAINTAINERS.md) cover the whole repo.
• Each subsystem has area maintainers — listed both in MAINTAINERS.md and CODEOWNERS. Tag the relevant area maintainer in the PR description.
• For specific people, the up-to-date contact list is in MAINTAINERS.md.

The four sub-pages cover what to do once you've picked up a task:

• Development workflow — branch, build, push, get reviewed.
• Testing — running and writing tests, coverage of the major suites.
• Debugging — useful tooling, logs, and pprof endpoints.
• Patterns and conventions — the unwritten rules embedded in the codebase.
• Tooling — the Makefile, golangci-lint, goyacc, promu, and CI.