Development workflow

The full lifecycle of a Prometheus PR, from branching to merge.

1. Set up your fork

git clone https://github.com/<your-user>/prometheus.git
cd prometheus
git remote add upstream https://github.com/prometheus/prometheus.git
git fetch upstream
git checkout -b my-feature upstream/main

The default branch is main. Release branches use the pattern release-<minor> (e.g. release-3.10).

2. Build and test locally

go build ./cmd/prometheus
go build ./cmd/promtool
make test               # runs Go + UI tests + lint + node version checks

For Go-only iteration:

make test GO_ONLY=1

The CI workflow at .github/workflows/ci.yml runs the same commands plus --tags=dedupelabels, --tags=slicelabels -race, --tags=forcedirectio -race ./tsdb/, a 386-bit run, and make protoc && make proto && git diff --exit-code to ensure protobuf regeneration is committed.

3. Write the change

Follow the patterns in Patterns and conventions. State your assumptions in code comments and document interface contracts (especially buffer-reuse semantics) at the interface, not the implementation.

If you are touching:

• A protobuf file (prompb/*.proto, prompb/io/...) — run make proto and commit the generated .pb.go.
• The PromQL grammar (promql/parser/generated_parser.y) — run make parser and commit the regenerated .y.go.
• The PromQL function set (promql/functions.go) — run make generate-promql-functions to refresh web/ui/mantine-ui/src/promql/functionSignatures.ts and functionDocs.tsx.
• The CLI flags (cmd/prometheus/main.go or cmd/promtool/main.go) — run make cli-documentation to refresh docs/command-line/prometheus.md and docs/command-line/promtool.md.
• The list of feature flags — update docs/feature_flags.md with a description and an example of --enable-feature=<name>.

Each of these is verified by a CI step that runs git diff --exit-code on the relevant files.

4. Commit

git commit -s -m "tsdb: avoid duplicate WAL writes when checkpointing"

Multiple commits are encouraged when each is independently meaningful (see AGENTS.md for the rule). Do not squash-on-merge — the project preserves commit granularity. Use a release-notes block in the PR description (not in commits).

5. Push and open the PR

git push -u origin my-feature

Open the PR against prometheus/prometheus:main. The PR template guides you to:

• Pick an area-prefixed title.
• Describe motivation.
• Add a release-notes block.
• Link issues with Fixes #NNNN.

The CI pipeline runs immediately. The required checks include Go tests, More Go tests, Go tests on Windows, UI tests, Mixins tests, golangci-lint, the buf protobuf lint, the release-notes check, and (for some PRs) prombench.

6. Review

• Code owners are notified automatically based on CODEOWNERS.
• General maintainers may also review.
• Address review comments with new commits where possible (do not force-push to rewrite history mid-review unless asked). When you do need to rebase, mention it explicitly.
• Use @-mention to ping a specific reviewer; for an unresponsive review, ask in #prometheus-dev.

7. Merge

Maintainers merge with rebase (preserves commits) or squash (single commit) depending on the PR's history. The merge button is configured per-repo and the commit message defaults to the PR title.

After merge:

• The CHANGELOG is updated by the release coordinator at release-cut time, not on merge.
• Any cherry-picks to release-* branches are opened as separate PRs by maintainers, prefixed Cherry-pick: <original PR>.

Branch protection and required permissions

.github/workflows/ci.yml and the protected main branch require:

• All required CI checks green.
• DCO sign-off on every commit.
• At least one maintainer approval.

Periodic chores

• Renovate (renovate.json) opens PRs to bump dependencies automatically. Maintainers automerge-dependabot.yml and renovate-bot PRs after CI passes.
• make update-all-go-deps updates the main module and the four sub-modules (documentation/examples/remote_storage, internal/tools, web/ui/mantine-ui/src/promql/tools, compliance).
• make bump-go-version updates Go minor versions across the codebase, driven by scripts/bump_go_version.sh.

Cherry-picking to a release branch

git fetch upstream
git checkout -b cherry-pick-<sha>-to-release-3.11 upstream/release-3.11
git cherry-pick -x <sha>
git push origin cherry-pick-<sha>-to-release-3.11

Open a separate PR against release-3.11 and prefix the title with [release-3.11].