Development workflow

This page summarizes how a change moves from a working tree to merged code on master.

Branching

ClickHouse follows a fork-and-PR model on GitHub. The trunk branch is master. Per AGENTS.md:

• Always create a new branch for a task; never commit directly to master.
• Don't rebase or --amend history while a branch is under review — add new commits instead. Reviewers rely on per-commit diffs.

Release branches are named vYY.M-stable (for the cut release) and vYY.M-lts (long-term support). Backports are usually performed by the release tooling, not contributors.

Pre-commit checks

Before opening a PR:

1. Build in debug and release with clang. CI builds many more flavours, but locally these two catch the bulk of issues.

2. Run the relevant test slice. For SQL tests:

   build/programs/clickhouse-test 00001_select_1

   For integration tests:

   python -m ci.praktika run "integration" --test test_name

3. Apply formatting:

   clang-format -i src/MyFile.cpp src/MyFile.h

4. If you added a setting, update the changelog block in the PR body (the template handles this).

Pull request template

.github/PULL_REQUEST_TEMPLATE.md is the canonical template. Per AGENTS.md, the PR body must:

• Open with a short description of the change and motivation.
• Pick exactly one Changelog category (Backward Incompatible Change, New Feature, Performance Improvement, Improvement, Bug Fix, Build/Testing/Packaging Improvement, CI Fix or improvement, Documentation, Removed Feature).
• Provide a Changelog entry (or Not for changelog for trivial chores).
• Tick the Documentation entry checkbox.

Do not invent a custom "Summary" / "Test plan" structure — the template is checked by tooling.

For CI fixes, link to the corresponding open issue if one exists. If a CI report URL was provided, include it in the commit message and PR body.

Continuous integration

CI is driven by Praktika, ClickHouse's in-house workflow runner. Configuration is in ci/:

• ci/jobs/ defines per-job logic.
• ci/docker/ defines the Docker images the jobs run in.
• ci/workflows/ defines the workflow graph.
• ci/praktika/ is the runner itself.

GitHub Actions in .github/workflows/ are mostly thin entry points that delegate to Praktika. The robot comment on a PR — not the GitHub Actions tab — is the source of truth for status. AGENTS.md explicitly directs contributors to look at Praktika reports first.

CI runs include:

Stage	Purpose
Style check	Clang-format, Clang-tidy, fixed-style violations (Allman, etc.).
Build matrix	Release, debug, ASan, TSan, MSan, UBSan; x86 + arm.
Stateless / stateful tests	Run against every build flavour.
Integration tests	Docker-compose based, sharded across many runners.
Performance comparison	Diff vs master reported as TSV; fetched via .claude/tools/fetch_perf_report.py.
Functional fuzzers	Continuous libFuzzer runs.

When a CI report fails, the robot leaves a link. Use the helpers under .claude/tools/ (see Tooling) to fetch and triage reports without opening a browser.

Merging

The bot squashes and merges PRs after all required CI checks pass and a reviewer approves. Force pushes to PR branches are discouraged once review starts; add new commits instead and let the bot squash at merge time.

Backports

A merged change can be backported into a release branch by labelling the PR (the release tooling watches for v*-must-backport labels). Backports themselves go through CI again. Trivial fixes are backported aggressively; new features are not.

Releases

The team cuts a release branch every month. Release notes are auto-generated into CHANGELOG.md by utils/changelog/. Build artifacts (deb/rpm/tgz/docker) are published from packages/ and docker/.

See also

• Testing
• Patterns and conventions
• Tooling