ClickHouse 更新日志条目编写指南面向用户的 Changelog 撰写规范与自动化流程【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse导读本指南基于 ClickHouse 官方《Changelog entry guidelines》系统讲解如何为 ClickHouse 的每个版本更新日志CHANGELOG撰写高质量条目。文中不仅覆盖从用户视角写作、保持简洁、遵循格式规范三大核心原则还结合当前仓库中的 PR 模板.github/PULL_REQUEST_TEMPLATE.md、CI 校验脚本ci/jobs/scripts/workflow_hooks/pr_body_check.py与变更日志生成工具tests/ci/changelog.py还原一条 changelog 条目从 PR 提交到最终落入CHANGELOG.md的完整链路。读完本文你将掌握为 ClickHouse 提交变更说明的标准写法并理解这些规范背后的自动化校验机制。为什么 ClickHouse 需要规范的 Changelog 条目良好的 changelog 条目能让用户快速理解每个版本带来了什么新东西、这些变化会如何影响他们。因此 ClickHouse 要求每位贡献者在提交 PR 时填写一条面向用户、便于阅读的 changelog 条目它会被收录进每个发布版本的更新日志中。在 ClickHouse 仓库中这个流程是强约束的而非仅靠自觉每个 PR 的正文必须从 .github/PULL_REQUEST_TEMPLATE.md 模板中选择Changelog category变更分类并填写Changelog entry条目内容模板本身还内嵌了指向本文档的链接。CI 会在 PR 检查阶段调用 ci/jobs/scripts/workflow_hooks/pr_body_check.py 解析 PR 正文若分类不合法或条目为空会直接以Invalid category: [...]或Changelog entry required for category ...报错拒绝。版本发布时tests/ci/changelog.py 会根据两个 git tag 之间的合并提交从 GitHub 抓取 PR解析每条 PR 正文中的分类与条目自动生成 Markdown 格式的更新日志写入 docs/changelogs 目录历史版本归档在 docs/changelogs/archive。也就是说你写的每一条 changelog 条目最终都会被机器解析、归类和格式化直接呈现在全球用户的版本发布说明中。写作质量直接影响用户对变更的理解。原则一从用户角度出发而不是从开发者角度出发changelog 条目的目的是向用户传达变更而不只是面向开发者。撰写条目时在合适的情况下尽量不仅说明变更了什么还要说明这项变更为什么对用户有帮助或者会如何影响用户。这个原则可以从 tests/ci/changelog.py 的解析逻辑中看到呼应脚本会截取 PR 正文中Changelog entry标题之后的全部非空行合并为条目并将首字母自动大写、自动补充结尾句号最终拼接为* {entry} #{pr_number} ({author}).的统一格式。既然条目会被独立呈现给用户它就必须在脱离 PR 上下文后依然自明。反例与正例对比不要这样写新增system.iceberg_history表请这样写用户现在可以通过新的system.iceberg_history表查看 Iceberg 表的历史快照。前者只陈述了加了什么表后者则回答了用户能拿它做什么。system.iceberg_history属于 ClickHouse 的系统表家族system数据库存放服务端内部状态表对这类变更用户最关心的是它带来的查询能力。再看函数类变更不要写添加stringBytesUniq和stringBytesEntropy函数用于搜索可能为随机或加密的数据。请写现在您可以使用新的stringBytesUniq和stringBytesEntropy函数检测字符串中可能经过加密或随机生成的数据从而帮助识别数据质量问题或安全隐患。这一对函数在仓库中真实存在位于 src/Functions/stringBytesUniq.cpp 与 src/Functions/stringBytesEntropy.cpp。从源码看stringBytesUniq通过 4×64 位掩码统计字符串中出现过的不同字节数返回UInt16配合stringBytesEntropy的字节熵计算确实可用于识别看起来随机/像加密数据的字符串。但条目若只写添加了某函数用户不知道什么时候该用它补充帮助识别数据质量问题或安全隐患这一句就把为什么有用说清楚了。原则二保持简洁避免使用用户在没有解释的情况下可能看不懂的技术术语。条目尽量控制在 1–5 句话内。此外ClickHouse 官方明确鼓励可以放心使用 LLM 来帮助检查拼写错误、语法问题或把条目改写得更易于用户理解这不算作弊我保证反例与正例对比不要这样写支持将关联子查询用作EXISTS表达式的参数而要这样写您现在可以在EXISTS子句中使用引用外层查询列的子查询。关联子查询correlated subquery是开发者术语引用外层查询列的子查询则是用户能直接理解的表述。一个清晰、简洁的条目示例允许按查询级别调整页缓存设置。这对于更快地进行实验以及针对高吞吐、低延迟查询进行微调非常必要。这个例子展示了简洁并不等于简陋第一句说做了什么per-query 粒度的页缓存配置第二句补充为什么需要加速实验、便于针对高吞吐低延迟场景微调。两句话信息完整。原则三遵循几条简单的格式规范格式规范看似是细枝末节但对机器解析和用户扫读都至关重要——因为 tests/ci/changelog.py 与 pr_body_check.py 都要按固定模式在 PR 正文中定位Changelog entry区块而最终发布的 changelog 是纯 Markdown 文本格式不统一会严重影响可读性。使用完整句子并使用一般现在时不要写成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.注意三点使用完整的句子而非短语片段动词使用一般现在时Fixes而非Fixed以句号结尾。后者并非可有可无——tests/ci/changelog.py 的generate_description()会在条目末尾缺少句点时自动补上.但主动写完整总比依赖机器修正更可靠。必要时使用反引号对配置项、函数名、SQL 语句、格式名称和数据类型等代码元素加上反引号。一般来说凡是你会输入到clickhouse-client中的内容都应该加上反引号。这样可以让更新日志条目更易读。不要写成配置项 use_skip_indexes_if_final 和 use_skip_indexes_if_final_exact_mode 现在默认值为 True请写成配置项use_skip_indexes_if_final和use_skip_indexes_if_final_exact_mode现在默认值为True反引号让用户能一眼区分代码元素与普通文字也方便后续被搜索引擎和文档工具索引。use_skip_indexes_if_final系设置是 MergeTree 跳过索引skip index在FINAL查询中的行为开关这类设置名本身没有可读语义反引号的标记作用尤其重要。尽量保持统一的格式尽量使用相同的结构它做了什么 → 为什么这对用户很重要 → 如何使用如有需要。这样读者就能更快浏览内容也更容易预期每条条目的写法。例如你现在可以在向量搜索前或后对结果应用过滤器从而更好地权衡性能与准确性。使用新的vector_search_filter_mode设置来选择你偏好的方式。这个例子完整套用了三段式结构行为过滤时机可选→ 价值权衡性能与准确性→ 用法vector_search_filter_mode设置。深入一条 Changelog 条目的完整旅程理解了写作规范后再看它在仓库中的落地链路会有更直观的把握。第一步PR 模板填写。贡献者在 .github/PULL_REQUEST_TEMPLATE.md 中从既定分类中勾选一项并填写Changelog entry。可选的分类清单与 tests/ci/changelog.py 中的categories_preferred_order完全对应Backward Incompatible Change向后不兼容变更New Feature新功能Experimental Feature实验性功能Performance Improvement性能改进Improvement改进Bug Fix (user-visible misbehavior in an official stable release)用户可见行为的 Bug 修复Build/Testing/Packaging Improvement构建/测试/打包改进Other其他同时存在两类不需要 changelog 条目的分类Documentation文档变更与CI Fix or Improvement/Not for changelogCI 修复或不重要的变更。tests/ci/changelog.py 通过归一化编辑距离Levenshtein阈值 20%做模糊匹配来识别这些豁免分类。第二步CI 校验。pr_body_check.py 中的check_changelog_entry()会解析 PR 正文剔除!-- ch-version-info --自动维护块过滤掉形如Close #12345的占位内容并校验条目非空、分类合法还会用 clickhouse_spelling_ignore.txt 之类的拼写检查拒绝非规范的 ClickHouse 产品名拼写。第三步自动生成更新日志。发布前运行python3 utils/changelog/changelog.py --from prev-tag next-tag该文件只是转发到 tests/ci/changelog.py 的包装脚本脚本会抓取两个 tag 之间的合并 PR → 按正文解析分类与条目 → 跳过 bot 作者如 dependabot与豁免分类 → 按categories_preferred_order排序输出 → 生成以#### {分类}分组的 Markdown 文件落到 docs/changelogs 下例如 v25.11.1.558-stable.md。你可以打开任意一个版本文件验证每条条目都是* 面向用户的描述 #PR号 (作者).的统一格式这正是前面所有写作规范的最终呈现。快速自查清单提交 changelog 条目之前用下面这份清单做最终检查视角条目是写给用户看的脱离 PR 上下文后依然能看懂吗完整性是否同时回答了做了什么和为什么/对用户有何影响简洁度是否控制在 1–5 句话是否混入了用户不熟悉的技术黑话时态与句式是否使用完整句子、一般现在时、以句号结尾代码元素配置项、函数名、SQL、格式名、数据类型是否都加了反引号结构与可扫读性是否符合做什么 → 为什么重要 → 怎么用的顺序分类正确所选分类在 PR 模板清单内且确实不属于可豁免 changelog 的类型遵循这些原则你的每一条 changelog 条目都将准确、易读并能顺利通过 ClickHouse 的自动化校验最终成为全球用户在版本说明中快速定位变更价值的可靠入口。【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考