Heuristic:Duckdb Duckdb PR Submission Strategy
| Knowledge Sources | |
|---|---|
| Domains | Workflow, Collaboration |
| Last Updated | 2026-02-07 12:00 GMT |
Overview
DuckDB strongly discourages large PRs and Draft PRs; split work into small, focused pull requests and merge frequently with main to avoid review bottlenecks.
Description
The DuckDB project has specific conventions around pull request management that differ from some other open source projects. Large PRs are explicitly called out as unlikely to be merged due to review difficulty. Draft PRs are discouraged in favor of using GitHub Issues or Discussions for work-in-progress conversations. The CI system only runs a complete check when a PR is marked as "ready for review", and submitting new changes to an open PR automatically moves it back to draft state.
Usage
Apply this heuristic before starting any contribution to DuckDB. Plan your work to produce small, reviewable PRs. Use it when deciding how to structure a multi-part feature implementation.
The Insight (Rule of Thumb)
- Rule 1: Avoid large pull requests. They are much less likely to be merged because they are incredibly hard to review.
- Rule 2: Split large issues into several smaller PRs that can be reviewed and merged independently.
- Rule 3: Do not open Draft pull requests. Use GitHub Issues or Discussions instead.
- Rule 4: Merge frequently with main when maintaining a branch to avoid divergence conflicts.
- Rule 5: Submit PRs to main frequently on bigger features (incremental delivery).
- Rule 6: Mark PRs as "ready for review" via the Web UI to trigger a complete CI run.
- Rule 7: Ensure you have all git tags from duckdb/duckdb before running CI: `git fetch <remote> --tags && git push --tags`
- Rule 8: Do not submit AI-generated PRs. Reviewing such PRs puts a considerable burden on maintainers.
- Trade-off: More PRs means more review cycles, but each cycle is faster and more focused.
Reasoning
Large PRs have exponentially increasing review complexity. A 500-line PR might take 30 minutes to review thoroughly, but a 2000-line PR could take several hours and is more likely to contain subtle bugs. Small PRs also reduce merge conflict risk and make git bisect more effective when tracking down regressions.
Code evidence from `CONTRIBUTING.md:22-33`:
## Outside Contributors
* Discuss your intended changes with the core team on Github
* Announce that you are working or want to work on a specific issue
* Avoid large pull requests - they are much less likely to be merged as they
are incredibly hard to review
## Pull Requests
* Do not commit/push directly to the main branch. Instead, create a fork and
file a pull request.
* When maintaining a branch, merge frequently with the main.
* When maintaining a branch, submit pull requests to the main frequently.
* If you are working on a bigger issue try to split it up into several smaller issues.
* Please do not open "Draft" pull requests. Rather, use issues or discussion
topics to discuss whatever needs discussing.
CI behavior from `CONTRIBUTING.md:37-40`:
* Pull requests will need to pass all continuous integration checks before merging.
* Submitting changes to an open pull request will move it to 'draft' state.
* Pull requests will get a complete run on the main repo CI only when marked as
'ready for review' (via Web UI, button on bottom right).