How to contribute

This section is for engineers who want to change ClickHouse. SQL users should look at the official user docs instead.

The official contributor handbook is at CONTRIBUTING.md. It covers the legal CLA process and links to the developer docs that ship with the repo (docs/en/development/). This wiki section summarizes the parts that matter most when reading or modifying the code:

• Development workflow — branches, commits, PR template, CI gating.
• Testing — the test layers, how to run them, how to add new tests.
• Debugging — sanitizers, fuzzers, stack-trace symbolisation, common pitfalls.
• Patterns and conventions — Allman braces, error handling, ASan-not-ASAN, no-sleep, etc.
• Tooling — c++expr, analyze-assembly.py, the .claude/tools/ helpers, Praktika CI.

Definition of done

A change is mergeable when:

1. It compiles in release, debug, ASan, TSan, MSan, and UBSan flavours. CI exercises all of them.
2. All test layers it touches pass: stateless, stateful, integration, performance, sqllogic, and unit. The Praktika comment on the PR is the single source of truth (more reliable than the GitHub Actions tab — see AGENTS.md).
3. New behaviour has new tests under tests/queries/0_stateless/ (per AGENTS.md, prefer adding a new test rather than extending an existing one). Use tests/queries/0_stateless/add-test to allocate a new file.
4. Public-facing changes have a changelog entry in the PR body, in the format the PULL_REQUEST_TEMPLATE expects.
5. Settings additions or renames are recorded in src/Core/Settings.cpp and reflected in system.settings. Tests cover the on/off paths.
6. Style passes: Allman braces, the .clang-format ruleset, the .clang-tidy checks, Python ruff, YAML lint.

How code review works

ClickHouse has dozens of code areas with dedicated reviewers. The repo does not ship a CODEOWNERS file with public mappings; reviewers are typically the people most active in the affected directory (see Maintainers). PRs are gated on Praktika CI and on at least one approving review. Bots (robot-clickhouse) handle the rebase/merge step.

Filing issues

Report bugs against https://github.com/ClickHouse/ClickHouse/issues with a reproducer (a .sql script that triggers the issue is best). Performance regressions belong to tests/performance/ and tend to get a dedicated comparison run.

Where to learn more

• VLDB 2024 paper: ClickHouse — Lightning Fast Analytics for Everyone — a great architectural primer.
• The docs/en/development/ directory in this repo — official developer guides.
• The Architecture page of this wiki — request lifecycle and major subsystems.