Workflow:ClickHouse ClickHouse Contributing Pull Request
| Knowledge Sources | |
|---|---|
| Domains | Open_Source, C++_Development, CI_CD |
| Last Updated | 2026-02-08 17:00 GMT |
Overview
End-to-end process for contributing code changes to the ClickHouse project, from forking the repository through passing CI checks and merging a pull request.
Description
This workflow covers the complete contributor journey for the ClickHouse open-source project. It encompasses setting up a development environment, making code changes, writing tests, submitting a pull request using the project's template, and navigating the CI system powered by the Praktika framework. The CI system automates building, testing across multiple configurations (Release, Debug, sanitizers), and reporting results. Contributors must sign the Individual CLA on their first pull request. The project follows specific coding conventions and review standards documented in the Copilot review instructions and contribution guidelines.
Usage
Execute this workflow when you want to contribute a bug fix, new feature, performance improvement, or documentation update to the ClickHouse project. This applies to both first-time contributors and regular committers.
Execution Steps
Step 1: Fork and Clone the Repository
Fork the ClickHouse repository on GitHub and clone your fork locally with submodules. Set up the upstream remote to track the main repository. Ensure all required submodules are initialized for the components you plan to modify.
Key considerations:
- Clone with `--recursive` or run `git submodule update --init`
- The `contrib/update-submodules.sh` script can selectively initialize needed submodules
- Set upstream remote: `git remote add upstream https://github.com/ClickHouse/ClickHouse.git`
- Create a feature branch from the latest master
Step 2: Set Up the Development Environment
Install the required toolchain (Clang compiler, CMake, Ninja) and configure the build. ClickHouse requires C++23 and uses Clang exclusively (GCC is not supported). Configure Python tooling as specified in `pyproject.toml` for any Python-based tests or utilities.
Key considerations:
- Clang is the only supported compiler
- C++23 standard is required
- CMake 3.25+ is required
- Multiple build directories can coexist (`build/`, `build_debug/`, `build_asan/`)
Step 3: Make Code Changes
Implement your changes following the project's coding conventions. ClickHouse enforces strict code quality: no `sleep` for fixing race conditions, no use of banned C functions (enforced by the `base/harmful/` library), and no unnecessary sanitizer tags on tests. The architecture document and Copilot review instructions provide detailed guidance on acceptable patterns.
Key considerations:
- Never use `sleep` in C++ to fix race conditions
- Avoid using functions banned by the `harmful` library
- Prefer adding new test files rather than extending existing ones
- Do not add "no-*" tags to tests unless strictly necessary
- Follow the "busybox-style" architecture when adding new sub-applications
Step 4: Write and Run Tests
Create stateless tests for your changes in `tests/queries/0_stateless/`. Each test needs a query file and a reference file with expected output. Run the tests locally against a development server to verify correctness. Use the `--record` flag to auto-generate reference files.
Key considerations:
- Test files: `.sql`, `.sh`, `.py`, `.expect`, `.sql.j2`
- Reference files: `.reference`, `.gen.reference`
- Tags go in the first line as a comment: `-- Tags: no-fasttest`
- Random settings limits can be specified: `-- Random settings limits: max_threads=(1, 4)`
- Reference files should use `default` for database names
Step 5: Submit Pull Request
Push your branch and create a pull request using the project's PR template. The template includes sections for changelog category, changelog entry, and a documentation checklist. Fill in the description clearly explaining the motivation and approach. On your first PR, the CLA bot will ask you to sign the Contributor License Agreement.
Key considerations:
- Use the GitHub PR template (`.github/PULL_REQUEST_TEMPLATE.md`)
- Select the appropriate changelog category
- Write a user-readable changelog entry
- Sign the CLA when prompted on first contribution
- Corporate CLA is available for employer-backed contributions
Step 6: Pass CI Checks
The Praktika CI framework automatically triggers builds and tests for the pull request. CI runs multiple build configurations (Release, Debug, ASan, TSan, MSan, UBSan) and executes stateless, stateful, and integration test suites. Monitor the CI results by checking the robot comment with Praktika report links. Fix any failures and push additional commits (do not use rebase or amend).
Key considerations:
- Check the robot comment for Praktika report links first
- GitHub Actions logs contain less information than Praktika reports
- CI jobs are defined in `ci/jobs/`, workflows in `ci/workflows/`, settings in `ci/settings/`
- Do not use rebase or amend; add new commits instead
- Sanitizer ignorelists exist for known false positives
Step 7: Address Review Feedback
Respond to code review feedback from maintainers. Make requested changes as new commits on the same branch. The Copilot review instructions document the project's review standards, including security checks, performance considerations, and coding style requirements.
Key considerations:
- Push new commits rather than amending or rebasing existing ones
- Address all review comments before requesting re-review
- The project has specific conventions: say "exception" not "crash" for logical errors, use ASan not ASAN
- Wrap literal names in inline code blocks in commit messages and documentation