How to contribute

This section is a working guide to the DuckDB development cycle. The canonical contribution policy is in CONTRIBUTING.md at the repository root and includes important rules that are non-negotiable:

• Pull requests generated by AI/LLMs are not accepted. Reviewing such PRs is a burden on maintainers.
• Do not commit directly to main. Fork, branch, and open a pull request.
• Avoid large pull requests. Split big issues into smaller ones.
• Ensure CI passes on your fork before opening a PR.

Workflow at a glance

graph LR
    Issue[Discuss intent on issue] --> Fork[Fork + branch]
    Fork --> Code[Code change]
    Code --> Test[Add sqllogictest / C++ test]
    Test --> Format[make format-fix]
    Format --> Build[make reldebug]
    Build --> CI[Push to fork, run CI]
    CI --> PR[Open PR to duckdb/duckdb]
    PR --> Review[Review + iterate]
    Review --> Merge[Maintainer merges]

Sub-pages:

• development-workflow — branching, PR hygiene, CI on forks.
• testing — sqllogictest, C++ tests, fuzzers, slow tests.
• debugging — debug builds, profiling, sanitizers, logging.
• patterns-and-conventions — coding style, error handling, memory management, naming.
• tooling — formatters, generators, build flags, helpful scripts.

Definition of done

A pull request is ready to merge when:

1. It is focused — one feature or one fix per PR.
2. It compiles in make reldebug and make debug builds.
3. make unit passes locally.
4. New behavior is covered by sqllogictest (.test / .test_slow) or, when SQL cannot express the case, a C++ test in test/api/.
5. The diff is formatted (make format-fix).
6. Generated files are regenerated when their inputs change (make generate-files).
7. The PR description explains the change, references the issue, and includes a reproduction case if it fixes a bug.

CI is the source of truth: even a clean local run does not guarantee that all 30+ workflows in .github/workflows/ will pass on every platform.

Where to start as a new contributor

• Browse the issue tracker for items labeled good first issue or help wanted.
• Read test/README.md and write a test that reproduces the behavior you want to change.
• Trace a failing query through the pipeline. The "Navigation tips" in CLAUDE.md and overview/architecture are the right starting points.
• Be aware that DuckDB releases on a quarterly cadence. Storage format changes need backward-compatibility tests in test/bwc/.