ClickHouse Changelog 条目编写指南：以用户为中心的发布说明写作规范与自动化落地-编程实验室

ClickHouse Changelog 条目编写指南：以用户为中心的发布说明写作规范与自动化落地

【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse

好的 changelog 条目能让用户快速理解「这次发布带来了什么、对我有什么影响」。本文围绕 ClickHouse 官方编写指南 docs/changelog_entry_guidelines.md 展开，结合仓库中的 PR 模板、changelog 自动生成脚本与 CI 流水线，系统讲解从「在 PR 描述里填写 changelog entry」到「它最终出现在 CHANGELOG.md 与各版本发布说明中」的完整链路，帮助贡献者写出专业、易读、可被自动收录的 changelog 条目。

Changelog 条目的定位：写给用户，而不是写给自己

ClickHouse 为每个 PR 都要求贡献者填写一段「用户可读」的 changelog entry，它会被收录进每个版本的 changelog 中。这份指南开篇就点明了核心立场：changelog 条目的读者是用户，而不只是开发者。因此在撰写时，除了说明「改了什么（what）」，还要尽可能传达「为什么对用户有用（why）」，以及「它如何影响用户（how）」。

反例与正例的对比非常直观：

❌ Addssystem.iceberg_historytable

✅ Users can now view historical snapshots of Iceberg tables using the newsystem.iceberg_historytable.

同样：

❌ AddstringBytesUniqandstringBytesEntropyfunctions to search for possibly random or encrypted data.

✅ You can now detect potentially encrypted or random data in your strings using the newstringBytesUniqandstringBytesEntropyfunctions, helping identify data quality issues or security concerns.

两者的差别在于：反例只陈述了「我们加了什么」，正例则把落点放在「用户现在能用它做什么、解决了什么场景问题」上。这正是本指南反复强调的以用户为中心的写作视角。

保持简单：1～5 句话，避免术语堆砌

指南要求条目力求简单，避免用户不假解释就无法理解的 jargon，长度控制在1～5 句话之间。同时指南明确鼓励使用 LLM 帮忙校对拼写、语法或改写得更用户友好——「这不算作弊」。

反例：

❌ Support correlated subqueries as an argument ofEXISTSexpression

正例：

✅ You can now use subqueries that reference outer query columns withinEXISTSclauses.

后者把 SQL 术语「correlated subqueries（相关子查询）」翻译成了用户能直接理解的描述「引用外层查询列的子查询」，并明确说清楚了在EXISTS子句中的可用性。

指南还给出了一条清晰的优秀示例：

Makes page cache settings adjustable on a per-query level. This is needed for faster experimentation and for the possibility of fine-tuning for high-throughput and low-latency queries.

这条条目用两句话完成了「改了什么 + 为什么需要」的闭环：先讲能力（页缓存设置可按查询级别调整），再讲动机（加速实验、便于对高吞吐与低延迟查询做微调）。

格式规范：三种必须遵守的写作纪律

使用完整句子与现在时

changelog 条目应写成完整句子，并使用现在时（present tense），让读者感觉「这个能力现在就可用」：

❌ Fixed a crash: if an exception is thrown in an attempt to remove a temporary file

✅ Fixes a crash where an exception is thrown in an attempt to remove a temporary file.

注意这里连标点都是规范的一部分：以句号结尾的完整句子，而不是冒号短语。

在必要处使用反引号

设置项、函数名、SQL 语句、格式名、数据类型等代码元素一律用反引号包裹。大致判断标准是：任何你会敲进clickhouse-client里的内容都应当加反引号。这能显著提升条目的可读性：

❌ Settings use_skip_indexes_if_final and use_skip_indexes_if_final_exact_mode now default to True

✅ Settingsuse_skip_indexes_if_finalanduse_skip_indexes_if_final_exact_modenow default toTrue

遵循统一的内容格式：做什么 → 为什么 → 怎么用

指南建议条目尽量遵循固定的三段式结构，使条目可快速扫读、对读者可预测：

What it does（做了什么）
Why it matters to the user（对用户为什么重要）
How to use it（如果需要，怎么用）

示例：

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 newvector_search_filter_modesetting to choose your preferred approach.

这条完美示范了三段式：能力（可在搜索前或后过滤向量搜索结果）→ 价值（更好地平衡性能与准确率）→ 用法（使用新的vector_search_filter_mode设置项）。

从 PR 模板到最终发布说明：条目的完整落地链路

撰写规范并非孤立存在，它与 ClickHouse 仓库的贡献流程深度绑定。

第一步：在 PR 模板中声明分类并填写条目

ClickHouse 的 .github/PULL_REQUEST_TEMPLATE.md 要求每个 PR 完成两件事：

选择 changelog category（保留其一）：

New Feature
Experimental Feature
Improvement
Performance Improvement
Backward Incompatible Change
Build/Testing/Packaging Improvement
Documentation（无需 changelog 条目）
Critical Bug Fix（崩溃、数据丢失、RBAC）
Bug Fix（官方稳定版中用户可见的错误行为）
CI Fix or Improvement（无需 changelog 条目）
Not for changelog（无需 changelog 条目）

填写 changelog entry：模板中明确要求填写「用户可读的简短描述」，并直接链接到本文所依据的编写指南 docs/changelog_entry_guidelines.md。

第二步：CI 脚本解析 PR 并自动生成 changelog

PR 合并后，tests/ci/changelog.py 负责生成原始 changelog。这个脚本体现了指南规范如何被工程化执行：

分类的规范化与排序：脚本定义了categories_preferred_order（Backward Incompatible Change→New Feature→Experimental Feature→Performance Improvement→Improvement→Bug Fix→Build/Testing/Packaging Improvement→Other），即发布说明中的分类展示顺序。同时对贡献者填写的分类做大小写、空白不敏感的归一化匹配，并支持 20% 归一化 Levenshtein 距离的模糊匹配，容忍拼写差异（见 tests/ci/changelog.py 与_match_changelog_category）。
自动跳过不需要进 changelog 的分类：Documentation、CI Fix or Improvement、Not for changelog以及历史遗留的 "not significant" 等表述都会被识别并跳过（_SKIP_CATEGORIES与_SKIP_LEGACY_PATTERN）。
条目格式化：每条最终渲染为* <entry> #PR号 (作者名).的标准格式（formatted_entry属性），其中裸的 issue 编号会被自动转换为链接。
绕过 PR 描述解析：脚本从 PR body 中按changelog category/changelog entry关键字解析出分类与条目内容，与模板结构一一对应；同时会跳过机器人作者（如dependabot[bot]）的 PR，并识别backport/分支以追溯被回移植的原始 PR。
使用方式：包装脚本 utils/changelog/changelog.py 提供了简单入口，底层调用tests/ci/changelog.py，支持--from/TO_REF指定 git ref 范围、--output指定输出文件、--repo指定仓库、--jobs控制并发请求数等参数。

第三步：夜间 CI 用 LLM 打磨条目

生成出的原始条目还需要经过人工编辑质量的打磨。ci/jobs/changelog_nightly.py 是一个「夜间任务」：它每天从合并到master的 PR 中增量生成原始 changelog 条目，插入到根目录 CHANGELOG.md 的 HTML 注释标记块中，然后按照.claude/skills/edit-changelog/SKILL.md的规则，通过codexCLI 调用 LLM 对原始条目进行重写、合并、分类调整，最后整合进进行中的发布版本小节。脚本会对 revert（回退）PR 做专门的书签追踪（Changelog-revert:/Changelog-deleted-entry:trailer），确保「被回退的条目被删除、回退又被回退时条目被恢复」这类跨多次运行的链条能被正确处理——这从侧面印证了指南中「让条目准确反映最终发布内容」的目标是由整套 CI 体系保障的。

第四步：沉淀为版本发布说明

最终成型的条目会同时沉淀在两个地方：根目录的 CHANGELOG.md（汇总全部发布历史）与 docs/changelogs/ 下按版本组织的发布说明文件，例如 docs/changelogs/v25.11.8.25-stable.md，其中每个条目都带有 PR 链接与作者署名，分类（Improvement、Bug Fix (user-visible misbehavior in an official stable release)、Build/Testing/Packaging Improvement等）与生成脚本的categories_preferred_order完全一致。

实战速查：写出合格条目的检查清单

结合指南全文与仓库落地机制，提交 PR 前可以用下面这份清单自检：

视角：条目是写给用户看的吗？是否只陈述了「我们加了 X」而没有说明用户能获得什么？
长度：是否控制在 1～5 句话？能用一句话说清的就不要写三句。
时态：是否用了完整句子 + 现在时（Fixes、Adds、You can now ...）？
反引号：设置项、函数名、SQL、格式名、数据类型是否都已用反引号包裹？
结构：是否遵循「做什么 → 为什么重要 → 怎么用（可选）」？
分类：PR 描述中的Changelog category是否选择了与改动性质匹配的分类（避免Not for changelog被误选导致条目静默丢失）？
格式：条目是否是单段落的可读文字，而不是列表、代码块或零散短语？CI 会把它渲染为* <条目> (#PR) (作者).的条目行。