How to contribute

This section covers the practical mechanics of working in the Neon repo: how to pick up work, how to format and lint, how to run tests, what to expect from review, and what tools you need installed locally.

For high-level project intent and code layout, start at Architecture. For setup, see Getting started.

Pull-request flow

The expected lifecycle is the one most Rust projects follow:

1. Branch from main. No long-lived feature branches; rebase on top of main before opening the PR.
2. Open a PR with a focused diff. "One change per PR" is the implicit rule. Splitting refactors from behavioral changes makes review tractable.
3. Get at least one approval. From CONTRIBUTING.md: "Get at least one +1 on your PR before you push." Smaller patches typically take a single review; large or cross-cutting ones go through more.
4. Keep CI green. Do not push to a PR that has a red CI even if you believe the failure is unrelated — the project asks contributors to help fix the root cause first.
5. Squash on merge. PR titles become commit messages on main; conventional-commit style (storage:, proxy:, compute:, chore:, fix:, feat:) is widely used but not strictly enforced. Look at the most recent dozen commits on main for current conventions.

External contributors trigger CI through a special "approved-for-ci-run" label: see .github/workflows/approved-for-ci-run.yml and the longer explanation in CONTRIBUTING.md. Maintainers must review the diff for safety before applying the label, because PRs from forks otherwise cannot access repository secrets.

Definition of done

A PR is "done" when, at minimum:

• It compiles with cargo build and cargo build --features=testing.
• ./run_clippy.sh is clean.
• ./scripts/reformat (rustfmt + ruff format + ruff check + mypy) is clean.
• Relevant cargo nextest run packages pass locally.
• If the change touches Python: poetry run ruff format ., poetry run ruff check ., and poetry run mypy . from the repo root all pass.
• For storage-system changes: at least one Python integration test exercises the new path, or there is an explicit reason in the PR description why one wasn't added.

The pre-commit hook (pre-commit.py, installed via make setup-pre-commit-hook) catches formatting and Python style before the push. CI catches the rest.

What's in the rest of this section

• Development workflow — branching, rebasing, splitting commits, dealing with the Postgres-fork submodules.
• Testing — Rust unit tests with cargo nextest, Python integration tests with pytest, simulation tests with desim.
• Debugging — log conventions, common failure modes, how to attach gdb/lldb to a crashed Postgres compute, flamegraphs.
• Patterns and conventions — error-handling style, async patterns, how tracing spans are used, naming.
• Tooling — cargo nextest, cargo deny, cargo hakari, ruff, mypy, make, redocly (for the OpenAPI specs), local CI helpers.

A note on the patched Postgres tree

vendor/postgres-v{14..17} are git submodules that hold lightly patched copies of upstream Postgres. Running make will check them out. If you change Postgres-side code (uncommon outside the compute team), you'll be working in those submodules, and your PR will need to pair with a PR in the neondatabase/postgres fork. See docs/core_changes.md for what kinds of changes Neon makes to Postgres and why.