Implementation:ClickHouse ClickHouse Gh Pr Create
| Knowledge Sources | |
|---|---|
| Domains | Development_Process |
| Last Updated | 2026-02-08 00:00 GMT |
Overview
Concrete tool for creating ClickHouse pull requests with the required structured template using the GitHub CLI, ensuring every contribution includes changelog categorization, user-facing description, and documentation metadata.
Description
The ClickHouse pull request submission process is implemented through a combination of a GitHub pull request template (`.github/PULL_REQUEST_TEMPLATE.md`) and the `gh` (GitHub CLI) tool for programmatic PR creation. The template defines a structured form that every pull request body must contain, organizing the information into three mandatory sections: changelog category, changelog entry, and documentation entry.
When a contributor creates a pull request, GitHub automatically populates the PR body with the contents of the template. The contributor then edits the template to select the appropriate changelog category (by deleting the non-applicable categories), writes a user-readable changelog entry, and fills in the documentation section. For programmatic PR creation (e.g., from CI scripts or developer tooling), the `gh pr create` command is used with an explicit `--body` argument that includes the filled-in template content.
Upon submission, GitHub's CLA bot checks whether the contributor has signed the ClickHouse Individual Contributor License Agreement. For first-time contributors, the bot comments on the PR with instructions for signing. This check must pass before the PR can be merged.
Usage
This implementation is used every time a contributor submits code changes to the ClickHouse repository. It applies to:
- Manual PR creation: Contributors create PRs through the GitHub web interface, which auto-populates the template.
- CLI PR creation: Contributors or automation scripts use `gh pr create` with the template content in the body.
- First-time contributions: The CLA bot automatically triggers on the first PR from a new contributor.
Code Reference
Source Location
- Repository: ClickHouse
- PR template:
.github/PULL_REQUEST_TEMPLATE.md(lines 1-35) - Contributing guide:
CONTRIBUTING.md(lines 1-22) - Changelog guidelines:
docs/changelog_entry_guidelines.md(lines 1-78)
Signature
gh pr create --title "<PR title>" --body "<filled-in PR template>"
PR Template Structure
### Changelog category (leave one):
- New Feature
- Experimental Feature
- Improvement
- Performance Improvement
- Backward Incompatible Change
- Build/Testing/Packaging Improvement
- Documentation (changelog entry is not required)
- Critical Bug Fix (crash, data loss, RBAC) or LOGICAL_ERROR
- Bug Fix (user-visible misbehavior in an official stable release)
- CI Fix or Improvement (changelog entry is not required)
- Not for changelog (changelog entry is not required)
### Changelog entry (a user-readable short description of the changes that goes into CHANGELOG.md):
...
### Documentation entry for user-facing changes
- [ ] Documentation is written (mandatory for new features)
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| Committed code changes | Git commits | Yes | One or more commits on a feature branch pushed to the contributor's fork of the ClickHouse repository |
| PR title | String | Yes | A concise summary of the change, suitable for the changelog and GitHub display |
| Changelog category | Enum (one of 11 values) | Yes | Exactly one category from the template's list; contributor deletes all non-applicable lines |
| Changelog entry | String | Conditional | A user-readable description (1-5 sentences, present tense, backtick code elements); not required for Documentation, CI Fix, or "Not for changelog" categories |
| Documentation checkbox | Boolean | Yes | Must be checked (marked with `[x]`) for new features; indicates whether documentation has been written |
| Documentation description | String | Conditional | Motivation, parameters, and example use for user-facing changes; optional but recommended |
| CLA signature | Legal agreement | Yes (first PR) | The ClickHouse Individual Contributor License Agreement, prompted by the CLA bot on the contributor's first pull request |
Outputs
| Name | Type | Description |
|---|---|---|
| GitHub Pull Request | PR object | A pull request on the ClickHouse/ClickHouse repository with the structured template body, assigned a PR number and URL |
| CLA bot check | Status check | A GitHub status check indicating whether the contributor has signed the CLA; blocks merge if unsigned |
| CI pipeline trigger | Webhook event | The PR creation event triggers the CI pipeline (Praktika framework) to begin building and testing the changes |
Usage Examples
Example: Creating a PR for a bug fix
gh pr create --title "Fix incorrect result for aggregate function sumIf with nullable argument" --body "$(cat <<'EOF'
### Changelog category (leave one):
- Bug Fix (user-visible misbehavior in an official stable release)
### Changelog entry (a user-readable short description of the changes that goes into CHANGELOG.md):
Fixes incorrect results from `sumIf` when the condition column is `Nullable`. Previously, NULL values in the condition were treated as true, leading to inflated sums.
### Documentation entry for user-facing changes
- [x] Documentation is written (mandatory for new features)
No new documentation needed; this is a bug fix for existing behavior.
EOF
)"
Example: Creating a PR for a new feature
gh pr create --title "Add vector search filter mode setting" --body "$(cat <<'EOF'
### Changelog category (leave one):
- New Feature
### Changelog entry (a user-readable short description of the changes that goes into CHANGELOG.md):
You can now filter vector search results either before or after the search operation, giving you better control over performance vs. accuracy tradeoffs. Use the new `vector_search_filter_mode` setting to choose your preferred approach.
### Documentation entry for user-facing changes
- [x] Documentation is written (mandatory for new features)
**Motivation:** Users performing approximate nearest neighbor (ANN) searches often need to combine vector similarity with traditional WHERE filters. The order of filtering affects both performance and result quality.
**Parameters:**
- `vector_search_filter_mode`: Controls when WHERE filters are applied relative to the vector search. Values: `pre_filter`, `post_filter` (default: `post_filter`).
**Example use:**
```sql
SELECT id, L2Distance(embedding, [1.0, 2.0, 3.0]) AS dist
FROM vectors
WHERE category = 'electronics'
ORDER BY dist LIMIT 10
SETTINGS vector_search_filter_mode = 'pre_filter'
```
EOF
)"
Example: Changelog entry guidelines
Good changelog entries follow these principles from docs/changelog_entry_guidelines.md:
BAD: "Adds system.iceberg_history table"
GOOD: "Users can now view historical snapshots of Iceberg tables using the new system.iceberg_history table."
BAD: "Fixed a crash: if an exception is thrown in an attempt to remove a temporary file"
GOOD: "Fixes a crash where an exception is thrown in an attempt to remove a temporary file."
BAD: "Settings use_skip_indexes_if_final and use_skip_indexes_if_final_exact_mode now default to True"
GOOD: "Settings `use_skip_indexes_if_final` and `use_skip_indexes_if_final_exact_mode` now default to `True`."