Generate PR descriptions for ClickHouse/ClickHouse that match maintainer expectations. Use when creating or updating PR descriptions.
Generate a good PR description and apply it, with optional confirmation based on user preference.
Plain description of what changed. No prefix conventions like fix(): or feat():.
Change default stderr_reaction to log_last for executable UDFsFix exception when inserting NULL into non-nullable column via CASTfix(udf): Change default stderr_reaction — conventional commits, ClickHouse doesn't use themFuzzer fixes — too vague, tells the reviewer nothingImprove error handling and enrich exit code exceptions with stderr context — too vague, doesn't say what was actually changedRead .github/PULL_REQUEST_TEMPLATE.md for the exact template structure.
A good PR description has two parts:
Explain to a future reader: what was the problem, why did it need fixing, what approach was taken, what were the results or trade-offs. This is the right place for:
Use plain paragraphs. Headers like ## Motivation, ## Changes, ## Results are fine and helpful — they make the PR easier to navigate for reviewers. Bullet lists are fine. Be as detailed as needed.
2. Template section (mandatory)
Fill in the changelog category (delete the rest of the list), write the changelog entry, and keep the documentation checkbox.
Exception — CI Fix or Improvement: omit the Changelog entry and Documentation entry sections entirely (they are not required). Keep the entire PR body under 100 words.
From #96110:
### Changelog category (leave one):
- Backward Incompatible Change
### Changelog entry:
The semantics of the `do_not_merge_across_partitions_select_final` setting were
made more obvious. Previously, the feature could be automatically enabled when
the setting was not explicitly set in the configs. It caused confusion repeatedly
and, unfortunately, led to some issues in production. Now, the rules are simpler:
`do_not_merge_across_partitions_select_final=1` enables the functionality
unconditionally. If `do_not_merge_across_partitions_select_final=0`, then automatic
is used only if the new setting
`enable_automatic_decision_for_merging_across_partitions_for_final=1` and not used
otherwise. To preserve the old behaviour as much as possible, the defaults were set
to `do_not_merge_across_partitions_select_final=0` and
`enable_automatic_decision_for_merging_across_partitions_for_final=1`.
### Documentation entry for user-facing changes
- [ ] Documentation is written (mandatory for new features)
---
The backward-incompatible part is that if someone has
`do_not_merge_across_partitions_select_final=0` explicitly set in the configs,
it no longer protects against the use of automatics. I'm open to discussion on
whether we should conservatively default to disabled automatics.
Note: extra context after --- is fine — reviewers see it, but only the changelog entry above the blank line goes into the CHANGELOG.
The entry is what ends up in the published CHANGELOG. Write it for a user who is upgrading and scanning for what affects them. The PR link and author attribution are appended automatically by tooling — do not include them.
Format: the changelog script (tests/ci/changelog.py) collects all lines after the ### Changelog entry: header up to the first blank line, then joins them with spaces into a single string. This means:
Tense: mixed is fine and natural. "Added X", "Fix a case where...", "The X setting is now Y" are all real examples from the CHANGELOG. Don't force everything into present tense.
Length: match the impact. A small new function can be one sentence. A changed default or backward-incompatible behavior warrants as many sentences as needed, including what users must do to adapt.
Specificity: always name the exact thing that changed. Never write "Fix a bug" or "Improve performance" without saying what specifically.
For backward-incompatible changes: always explain the old behavior, the new behavior, and how to restore the old one if possible.
Real examples from the ClickHouse CHANGELOG:
One sentence, sufficient for a focused addition:
Add
xxh3_128hashing function.
One sentence with enough context:
DATEcolumns from PostgreSQL are now inferred asDate32in ClickHouse (in previous versions they were inferred asDate, which led to overflow of values outside a narrow range). Allow insertingDate32values back to PostgreSQL.
Full migration instructions for a default change:
Deduplication is turned ON for all inserts by default. It was OFF before for async inserts and for MV's, but it was ON for sync inserts. The goal is to have the same defaults for both ways of inserts. If you have deduplication explicitly disabled on your cluster, you have to explicitly set
deduplicate_insert='backward_compatible_choice'to keep the old behavior.
Describes new capability with enough detail to understand when to use it:
Added
OPTIMIZE <table> DRY RUN PARTS <part names>query to simulate merges without committing the result part. It may be useful for testing purposes: verifying merge correctness in the new version, deterministically reproducing merge-related bugs, and reliably benchmarking merge performance.
Reference the issue if one exists: Closes #XXXXX or Fixes #XXXXX at the end.
These patterns make PRs harder to read or signal low effort:
fix(scope): / feat(): / chore(): — ClickHouse doesn't use conventional commitsThis PR ... to start any section — just describe the changeFuzzer fixes, Fix bug, Improvements — always say what specificallyIt's fine to mention AI assistance openly. Co-Authored-By: in commits or acknowledgements in the PR description are acceptable — ClickHouse is open about AI-assisted development.
When creating a PR, open it as a Draft — this prevents accidental merges.
Before creating or updating the PR, check user memory for a confirmation preference. If no preference is stored and the session is interactive, ask once: "Should I always show you the description for approval before applying it, or just go ahead every time?" Save the answer to memory and apply it from then on. If the session is non-interactive, proceed directly without asking.
If the current repository is a fork (i.e. git remote get-url origin does not contain ClickHouse/ClickHouse), always target the upstream repository. Pass --repo ClickHouse/ClickHouse to gh pr create and set --head <fork-owner>:<branch> so the PR is opened against the canonical repo, not the fork.