Principle:ClickHouse ClickHouse Pull Request Submission
| Knowledge Sources | |
|---|---|
| Domains | Development_Process, Code_Quality |
| Last Updated | 2026-02-08 00:00 GMT |
Overview
Structured pull request creation with changelog categorization enables automated release management by requiring contributors to classify changes and provide user-facing descriptions in a standardized template.
Description
The ClickHouse project enforces a structured pull request submission process that serves multiple purposes beyond simple code contribution. Every pull request must include structured metadata that feeds directly into the project's release pipeline: a changelog category, a user-readable changelog entry, and documentation information. This metadata-driven approach transforms pull requests from informal code review requests into formal, machine-parseable release artifacts.
The pull request template mandates three key sections:
1. Changelog category: Contributors must select exactly one category from a predefined list that determines how the change appears in release notes. Categories include:
- New Feature and Experimental Feature for new capabilities
- Improvement and Performance Improvement for enhancements to existing functionality
- Backward Incompatible Change for changes that alter existing behavior
- Bug Fix and Critical Bug Fix (crash, data loss, RBAC, or `LOGICAL_ERROR`) for corrections
- Build/Testing/Packaging Improvement for infrastructure changes
- Documentation for documentation-only changes (no changelog entry required)
- CI Fix or Improvement for CI infrastructure (no changelog entry required)
- Not for changelog for internal changes that do not warrant a changelog entry
2. Changelog entry: A user-readable description written from the user's perspective, following the project's changelog entry guidelines. Good entries explain not just what changed but why and how it affects the user. Code elements such as settings, function names, and SQL statements should be backtick-quoted. Entries should be written in full sentences in the present tense.
3. Documentation entry: A checkbox indicating whether documentation has been written (mandatory for new features), plus an optional description of motivation, parameters, and example usage for user-facing changes.
Additionally, the project requires a Contributor License Agreement (CLA) for first-time contributors. A bot automatically detects first-time pull requests and prompts the contributor to sign the ClickHouse Individual CLA. Organizations may optionally sign a Corporate CLA.
Usage
This principle applies to every code contribution to the ClickHouse repository:
- New contributors: Must sign the CLA when prompted by the bot on their first pull request.
- All contributors: Must fill out the PR template completely, selecting the appropriate changelog category and writing a clear changelog entry.
- Feature contributors: Must check the documentation checkbox and either include documentation changes in the same PR or provide sufficient information for documentation to be written.
- Bug fix contributors: Should distinguish between critical bug fixes (crash, data loss, RBAC, or `LOGICAL_ERROR`) and regular bug fixes (user-visible misbehavior in an official stable release).
Theoretical Basis
The structured pull request submission model is based on the principle of metadata-at-source: capturing release-relevant information at the point where the contributor has the most context about the change, rather than attempting to reconstruct this information later during release preparation.
This approach addresses several challenges in large-scale open-source release management:
1. Changelog automation: By requiring contributors to select a category and write a user-readable description, the release process can automatically assemble changelogs from merged pull requests. The category determines the section of the changelog, and the entry provides the content. Changes marked as "Not for changelog," "Documentation," or "CI Fix or Improvement" are excluded from the user-facing changelog.
2. Release impact classification: The category taxonomy is designed to map directly to user concerns:
- Users upgrading between versions need to know about backward incompatible changes first.
- Users evaluating upgrades want to see new features and performance improvements.
- Users experiencing issues want to find relevant bug fixes.
- Critical bug fixes (crash, data loss, RBAC) are distinguished from regular bug fixes to highlight urgency.
3. Documentation coupling: Requiring documentation information in the PR template ensures that user-facing changes are accompanied by documentation. The mandatory checkbox for new features creates accountability, while the structured description template (motivation, parameters, example) provides a minimum documentation framework even when full documentation is deferred.
4. Legal compliance: The CLA bot integration ensures that every contribution has a clear legal standing before it can be merged. The bot triggers automatically on first pull requests, minimizing friction for repeat contributors while maintaining legal coverage.
5. User-centric communication: The changelog entry guidelines emphasize writing from the user's perspective rather than the developer's perspective. This transforms technical implementation details into actionable information for database administrators and application developers. For example, instead of "Added `system.iceberg_history` table," the preferred form is "Users can now view historical snapshots of Iceberg tables using the new `system.iceberg_history` table."
The overall design philosophy treats each pull request as a self-contained release artifact that carries not only code changes but also the metadata needed to communicate those changes to users, generate release notes, and maintain legal compliance.