Edit Changelog

ClickHouse Changelog Editing Skill

What this skill does

The autogenerator (utils/changelog/changelog.py) converts every PR description in the release range into a bullet under the category the author picked. The maintainer then heavily edits that output before it lands in CHANGELOG.md. This skill applies those edits.

The patterns below were derived by diffing the autogenerated commit and the following "edited" / "Cleanup" commit for releases 25.2, 25.3, 25.5, 25.7, verifying against PR descriptions for 26.4, and from the manual edits the maintainers still had to make after the skill-assisted passes for 26.6 and 26.8. Don't invent new conventions — if a pattern isn't here, leave the entry alone.

Arguments

• $0 (optional): path to the auto-generated changelog file (the output of utils/changelog/changelog.py --output=...). Edit this file in place.

If $0 is omitted, default to editing the most recent release section in CHANGELOG.md. Identify it by the first ### <a id="..."></a> ClickHouse release X.Y, ... heading, and treat the slice from that heading up to the next ### <a id= heading as the input. This is the common case after the maintainer has already pasted the autogenerated output into CHANGELOG.md.

Workflow

1. Read the input file. Confirm it has the autogenerator's structure: a ### ClickHouse release ... FIXME ... header followed by #### <Category> sections of * <entry>. [#NNN](...) ([Author](...)). bullets. The input can hold several such blocks, one per generation run (the NightlyChangelog job appends a new raw block every night, and keeps the earlier ones when their edit was rejected). Treat all of them, together with the in-progress section, as one input: process every block in the same pass, integrate all of it into the one in-progress section, and leave no block behind. A revert in a later block cancels an entry in an earlier block exactly as it cancels one in the in-progress section - the blocks are not separate releases, only separate days of the same one.
2. Make the edits described under "Edits" below, in the order listed.
3. After each substantive change, show the user a short summary (one line per non-trivial edit) — don't dump the whole diff.
4. When done, do not commit or paste into CHANGELOG.md automatically. Tell the user the file is ready; they will paste it into CHANGELOG.md themselves and commit.

Edits, in order

Each edit type below was observed at least twice across the surveyed releases. For real before/after examples, consult the diffs listed at the bottom under "How to use the surveyed past releases".

Retention rule — read this before deleting anything. An entry that the autogenerator put under one of the real categories (Backward Incompatible Change, New Feature, Experimental Feature, Performance Improvement, Improvement, Bug Fix) is never deleted. Rewrite it (§5), merge it into another bullet (§7), move it to another category (§6) — but its [#NNNNN](...) link stays in the file. Deletion is confined to three places: the NOT FOR CHANGELOG / INSIGNIFICANT and NO CL ENTRY bullets that carry no user-visible change (§3), the Build/Testing/Packaging Improvement entries that are pure CI plumbing (§4), and an entry that a revert cancels out — and that no later revert of that revert brings back (§2). "This looks unimportant" is not a reason to drop a real entry — an entry lost here is lost for good, because the changelog is generated once per range.

The NightlyChangelog CI job enforces exactly this: a run whose edit drops such a link fails with Entries disappeared in the edit without a matching revert, and the raw entries stay unedited until someone fixes it. That was the state of the 26.8 changelog for twelve days in August 2026.

1. Release header

The autogenerator emits:

### ClickHouse release {TO_REF} ({sha11}) FIXME as compared to {FROM_REF} ({sha11})

Replace it with:

### <a id="NNN"></a> ClickHouse release X.Y[ LTS], YYYY-MM-DD. [Presentation](https://presentations.clickhouse.com/YYYY-release-X.Y/), [Video](https://www.youtube.com/watch?v=...)

Where NNN is the version with dots removed (26.4 → 264). The X.3 and X.8 releases of each year are LTS — add the LTS marker for those automatically (26.8 → v26.8 LTS); for any other version add it only if the user says so. The same LTS marker goes into the TOC line. If the presentation and video links aren't known yet, leave a FIXME placeholder and tell the user to fill them in — don't invent URLs. While the release is still being prepared, the header keeps a trailing , FIXME (in progress) after the date (e.g. ClickHouse release 26.8 LTS, 2026-08-27, FIXME (in progress)); the finalization commit removes it.

The TOC at the top of CHANGELOG.md also needs a new line; only do this if the user is editing CHANGELOG.md directly.

2. Resolve #### NO CL ENTRY against the rest of the changelog

These are revert PRs (Revert "...") that the autogenerator includes because the revert PR has no Changelog entry. Walk every bullet in this section. For each:

A revert is not always in this section. The autogenerator renders the author's own Changelog entry under the author's own Changelog category, so a revert whose author filled both in appears as an ordinary bullet — under Improvement, reading "Disable the setting again", with nothing to give it away. The opposite disguise is a bullet whose whole text is an HTML comment, <!-- CI automatic block start :ci_links: -->: the pull request body had no changelog entry at all, and the generator took the first line it found. Under NOT FOR CHANGELOG / INSIGNIFICANT most of those are automatic reverts merged by the Revert CI regressions job (the body starts with Reverts owner/repo#NNNNN); the rest are bot pull requests such as the nightly documentation regeneration. Open every one of them with gh pr view before deciding - a revert hidden this way cancelled an entry of the same run twice in September 2026 and was missed both times. When a bullet undoes something you have seen in this release, check its PR (gh pr view <N> --json title,body; the title of a revert says Revert, and GitHub adds a Reverts owner/repo#NNNNN line to the body) and treat it by the rules below. Such a revert's own bullet is deleted with the entry it cancels, exactly like one from this section — the "never delete a real entry" rule does not protect it, because it is not a change that ships. A revert that undoes something of this release and something from an earlier one at the same time is the exception: the second half is user-visible, so it keeps an entry of its own (case 5 below) — its link appended to the entry it re-applied is an annotation on that entry, not a substitute for its own.

"Something of this release" includes a PR whose entry was pruned earlier under §3 or §4: the change was still made and undone inside the range, so the revert has no user-visible effect either. It does not include a PR whose entry is already in a released section — merged into the last release branch after this cycle started, so users have the behaviour — and reverting that is case 5.

Deleting the entry is only half of it — the revert must not be left behind as an entry of its own either, whatever category the autogenerator gave it. The user should see no trace of either side. The one place such a PR still appears is as the appended link on an entry it re-applied (§2.5), where it records the re-apply rather than describing a change.

1. Read the title of the revert PR (gh pr view <N> --json title,body) to identify which earlier PR it reverts. Most reverts have a title of the form Revert "<original PR title>" or Revert #NNNNN, and GitHub puts a Reverts owner/repo#NNNNN line into the body (a hand-written revert often spells it as a link, Reverts https://github.com/owner/repo/pull/NNNNN). When the target is itself a revert - the title reads Revert "Revert "...", or the target's body carries its own Reverts line - open the target too and follow the chain down to the pull request that is not a revert: that is the entry the chain is about, and it was usually processed days ago, so nothing in the current input names it.

2. Search the rest of the in-progress changelog for the matching entry by PR number, title, or topic.

3. Check whether this revert is itself reverted before you conclude anything — by a Revert "Revert "...""" title elsewhere in the section, or by a body containing Reverts owner/repo#<this PR>. If it is, the change ships in this release: go to step 6 and leave the original entry in place. A three-PR chain (change, revert, revert of the revert) sits entirely inside one range often enough to matter, and when the release is edited incrementally, the chain is spread over several of those increments (step 6).

4. If the original PR is in the same release range and stays reverted: delete that entry from its category. Do not keep the revert PR as a separate bullet — the user should see no trace of either.

5. If the original PR shipped in an earlier release and the revert is meant to be visible to users: rewrite the revert into a normal entry under the appropriate category (often Bug Fix or Backward Incompatible Change), describing the user-visible effect of the revert.

6. If the revert PR is itself a revert-of-revert (i.e. it re-applies a change that was previously reverted): keep the original entry, append the second revert's PR/author link to it so both PR numbers are recorded, and delete the intervening revert from the section.

   Real example from 26.8: #109946 fixed the propagation of settings in accurateCastOrDefault, #114911 reverted it, #114912 reverted that revert. All three are in the range. The result is one Bug Fix bullet — #109946's entry with #114912's link appended — and no trace of #114911. Deleting #109946 "because it was reverted" drops a fix that ships in the release.

   When a release is edited in daily increments, the three PRs arrive on three different days: the entry was integrated on the first day, deleted on the second, and the third brings only the revert of the revert. The original entry is then not in the file to be kept — it has to be re-added from the text it had when it was deleted, which the caller supplies (the NightlyChangelog job lists such entries with their previous text and category under "Entries to restore"). If nothing supplies it, reconstruct the entry from the original PR with gh pr view <N> --json title,body; do not leave the release without it.

   A bullet that covered several PRs comes back as one bullet carrying all of them, not as one bullet each — splitting it undoes the merge of §7. That includes the PRs of that bullet which never left: re-adding the entry beside the surviving bullet duplicates the prose even though no PR link repeats, so merge it into that bullet instead. A revert can be one of those PRs — a revert of an earlier release is a normal entry (case 5) and can have been merged like any other; what is not a PR of the bullet is the link a previous restoration appended to record a re-apply. And if only some of those PRs were re-applied, leave the others' links off: their reverts still stand, so those changes are not in the release, even though the recorded text attributes them.

   The link of the PR that re-applied the change goes on the restored entry, as in the main rule above: its own revert bullet is deleted, so that link is the only trace of the re-apply left in the release. A change can be taken out and put back more than once in a cycle — #109946 out by #114911, back by #114912, out by #115500, back by #116000 — and then every PR that put it back belongs on the entry, not just the first. The ones that took it out leave no trace.

   One revert can revert several PRs at once. When such a revert is itself reverted, every entry it brings back records that revert-of-revert, so the same link appears on each of them — that is not the same as one entry written twice. And a revert rewritten into a visible entry (case 5 above) is an entry like any other: if it is deleted and later restored, it takes the link of the PR that restored it too.

   An entry the autogenerator had filed under NOT FOR CHANGELOG or as CI plumbing and that was never added to the release is offered back, not required: §3 and §4 were free to prune it, so decide again whether it describes a user-visible change. One that had already been added is required — that decision was made when it went in. What matters is that the choice is possible — the entry is quoted for you because nothing in the file remembers it any more.

   When the restoration merges into a surviving bullet, it lands under that bullet's current category — which a later edit may have moved. Otherwise, restore it under the category it was in, which is not necessarily the one its PR declares: the entry may have been promoted out of NOT FOR CHANGELOG (§3) or moved (§6) by the edit that first added it, and re-deriving the category from the PR would undo that.

   If the deleted entry shared a bullet with other PRs (§7) and those are still in the in-progress section, that bullet is still there too: append the missing PR link to it instead of adding a second bullet. The same PR appearing in an already-released section further down is not that bullet. No PR may end up attributed twice within one section — one [#NNNNN](...) ([Author](...)) per PR.

   A restored PR needs its own attribution, [#NNNNN](...) ([Author](...)). A bare [#NNNNN](...) link inside somebody else's bullet — a This closes reference, a follow-up named in prose — is not that PR's entry and does not count as restoring it.

7. After processing, delete any leftover bullets and the section header itself.

The goal is that the final changelog reflects the net effect on the release: a PR that landed and then got reverted shouldn't appear at all, and one whose revert was itself reverted appears with every PR that put it back. Both halves are enforced by the NightlyChangelog job — keeping a reverted entry fails it just as dropping a real one does.

Reverts can postdate your input. The changelog is built incrementally, so a PR whose entry is already in the file can be reverted after the range your input was generated from — no NO CL ENTRY bullet will ever tell you about it. On the final pass, search the merge history since the last generation run for Revert-titled PRs (git log --oneline --grep='^Revert' <last-generated-sha>..origin/master or gh pr list --state merged --search 'Revert') and delete the entries of anything reverted. In 26.8, the entry for #111973 had to be removed by hand (#116504) because the revert landed after the entry was written. If the change was reverted but a revert-of-revert is expected before the release, keep the entry and prepend TODO: wait for the revert-of-revert. instead of deleting it (see §9 for the TODO flag convention).

3. Drop entire #### NOT FOR CHANGELOG / INSIGNIFICANT section, but rescue user-visible entries

Walk every bullet in this section. For each:

• If the entry mentions a user-visible behaviour (function/setting name, a Fix for a real bug, a perf change with a number, a new column in a system table, etc.) — promote it into the appropriate category (use the rules in §6 to pick the category). Don't strip the content; only strip developer-internal preambles like "fix msan ...", "ci: ...". If after stripping there is no real user-facing description, drop the entry instead of promoting an empty one.
• Otherwise — delete it.

Then delete the section header itself. This section, NO CL ENTRY and the CI plumbing of §4 are the only places where entries are deleted; see the retention rule above.

This closes / Closes #N / Fixes #N entries

These are valuable — they tie the change to the issue tracker. Keep them, don't strip. Apply this shape:

• The issue reference belongs at the end of the entry, after the description text, not at the start.
• The reference must be a markdown link to the issue (Closes [#NNNNN](https://github.com/ClickHouse/ClickHouse/issues/NNNNN)), not a bare #N or a raw URL. The autogenerator already converts most of these — re-check.
• If the entry is only Closes #N. with no description, fetch the PR body or the linked issue title and write a one-sentence description of what the user observes, then put Closes [#N](...) at the end.
• Multiple Closes/Fixes references can stay; put them all at the end.

Examples of entries that should be promoted (from past releases):

• Fix renames of columns missing in part. → Bug Fix.
• Write Parquet bloom filters. → New Feature.
• Reverse key support in PartsSplitter. → Bug Fix (it had been gated as experimental but was shipping).

Examples that should be deleted:

• update arrow submodule for table reader fixes. (build plumbing)
• tests: ..., ci: ..., Fix flaky test_*, Update README.md.
• Sync private., Add a test for [#NNNNN]. (no user-visible change).

4. Prune #### Build/Testing/Packaging Improvement

Most CI infrastructure entries (praktika, internal CI fixes, integration-test plumbing, fast-test tweaks) are removed. Only items that affect external users or distributors stay. Keep:

• Toolchain/dependency bumps a user might notice (Bump curl to ..., Update to embedded LLVM 19, Restore QPL codec).
• Build-system changes that affect packagers / contributors building from source (Raise minimum required CMake version to 3.25, Support build HDFS on both ARM and Intel mac, Fixes to allow building with clang20).
• Docker image behaviour visible to users (Disable network access for user default in docker image.).

Delete:

• Anything starting CI:, ci:, tests:, Fix flaky , Disable test, Bump pytest, Update version_date.tsv, Switch ... workflow, Praktika ..., Sync ..., Refactor , chcache: (unless it's a user-relevant build issue).
• Internal coverage / digest / scheduling / artifact-path tweaks.

5. Per-entry text rewrites

For every remaining bullet, in the order below:

5a. Strip leading filler

• A literal leading ... produced by the autogenerator's bullet cleanup — delete it.
• TBD. / TODO: ... / WTF is that? — the entry is unfinished. Either rewrite it from the PR title, or delete and tell the user. This applies to author-left TODOs only — a TODO: that the maintainer (or a previous editing pass) prepended as a release-blocking flag stays until its issue is resolved; see §9.
• What: prefix produced by Cursor/AI bot PRs — delete the prefix.
• This PR ... / Changes in this PR: 1. ... / In this PR ... — rewrite to start with the user-visible effect.
• Doing the rewrite in the last major PR ... / first-person developer context — delete or rewrite.
• Follow up for https://...PR/N. / Follow-up to [#N]. with no other description — delete the entry; it has no user-facing content. If there is real content after the follow-up reference, keep just that.
• An entry that is a real, user-visible change but is written incomprehensibly (only in terms of internal classes/methods, e.g. naming MergeTreeSink::consume and a delayed_chunk pattern instead of the observable effect) — do not leave it and do not delete it. Open the PR (gh pr view <N> --json title,body), read what it actually does, and write a proper user-facing entry from scratch (keep the original PR/author link). Example: PR #105943's autogenerated entry described delayed_chunk/StorageSnapshot internals; the PR adds the setting wait_for_part_commit_in_dependent_materialized_views, so the correct entry describes that setting and the observable effect (a cascading MV that joins back to its source can now see the row being inserted). Never ship a TODO/FIXME placeholder in its place.

5b. Strip trailing artifacts

• An entry whose whole text is wrapped in bold, ending with a doubled period — **Reject PromQL timestamps and durations that exceed the Int64 range.**. — strip the ** markers and the extra period. This comes from PR bodies whose changelog entry is written in bold; 26.8 had six of these from one author and they all had to be fixed by hand.
• ### Documentation entry for user-facing changes and anything after it — the autogenerator sometimes captures this from PR bodies. Cut it.
• "I'll write more info later." / "TODO: explain better" — cut.
• A bare PR/issue URL left inline in any phrasing (not just Closes/Fixes) — convert it to the markdown-link form. E.g. Follow up to https://github.com/ClickHouse/ClickHouse/pull/106387. → Follow up to [#106387](https://github.com/ClickHouse/ClickHouse/pull/106387).

Do not strip trailing Closes #N / Fixes #N / Closes [#N](...) references. They are valuable. If they're at the start of the entry, move them to the end after the description. If they're a bare URL like Closes: https://github.com/ClickHouse/ClickHouse/issues/N, convert to the markdown-link form Closes [#N](https://...) (the autogenerator already does this for most cases — re-check). See §3 for the full "Closes/Fixes" rule.

5c. Backtick code-like tokens (most frequent edit by far)

Anything you would type into clickhouse-client should be in backticks. Specifically:

• Functions without parens: geoToH3() → geoToH3, ToTime → toTime, extractKeyValuePairs, tokens, countMatches, printf, etc. The project rule (CLAUDE.md): "write names of functions and methods as f instead of f() — we prefer it for mathematical purity." Table functions count too, including in a comma list: file() / s3() / azure() / url() → file / s3 / azure / url.
• Literal keyword/value names that name a feature variant read like ordinary words but are still literals — backtick them: statistic types (basic, countmin, minmax, tdigest), codec names, layout names, mode strings. E.g. "Support basic statistics", not "Support basic statistics".
• Settings: parallel_inserts, s3_slow_all_threads_after_network_error, geotoh3_lon_lat_input_order, enable_url_encoding, etc.
• Types: Time, Time64, JSON, Variant, BFloat16, Decimal, LowCardinality, Array, Tuple, Nullable, Map, Float32, Float64, IPv4, IPv6, Date32, DateTime64.
• Engines / formats / catalogs: MergeTree, ReplicatedMergeTree, Iceberg, DeltaLake, Kafka, Parquet, Arrow, S3Queue, RabbitMQ, Redis, KeeperMap, PostgreSQL, MySQL, Azure. (The autogenerator usually doesn't backtick these.)
• SQL fragments: SET TIME ZONE 'tz', SET session_timezone, ALTER TABLE ... MOVE|REPLACE PARTITION, RENAME COLUMN, DROP COLUMN, CODEC(ZSTD, DoubleDelta), CREATE TABLE, SELECT ... FROM ....
• Special tokens: -If combinator, version-hint.txt, _part_offset.
• Type-conversion and pseudo-code expressions: each conversion pair goes into one backtick span — DateTime64(x) <-> DateTime64(y), Decimal(x) <-> Decimal(y), Float32 <-> Float64 (a 26.8 entry listing these bare had to be fixed in a follow-up commit).
• Bundled tool names keep their literal lowercase form in backticks: chdig, not "Chdig".

Don't backtick prose nouns (the user, a query, the index) — only literal identifiers and code.

5d. Capitalize proper nouns

iceberg → Iceberg, azure → Azure, delta lake / delta-kernel → DeltaLake, parquet → Parquet, kafka → Kafka, rust → Rust, postgres → PostgreSQL, mysql → MySQL. (Skip if the word is already inside backticks as a literal config value.)

5e. Type-name compounds

Capitalize compounds like float-to-string → Float-to-String when used as a noun (e.g. "Faster Float-to-String conversion").