ClickHouse Changelog 条目编写指南从 PR 描述到发布日志的最佳实践【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse本文围绕 ClickHouse 仓库的官方文档 docs/changelog_entry_guidelines.md及对应的俄语版本 docs/ru/changelog_entry_guidelines.md展开系统讲解如何为 ClickHouse 编写高质量、面向用户的 changelog 条目并结合 tests/ci/changelog.py 等仓库源码说明这些规则在 PR 解析、CI 校验与版本发布流水线中如何被强制执行。读完本文你将掌握一条 changelog 条目从 PR 描述到最终发布日志的完整生命周期并能写出结构一致、可读性高、可直接进入CHANGELOG.md的条目。为什么 changelog 条目对 ClickHouse 如此重要ClickHouse 以每月 12 个版本的节奏持续发布每个版本都伴随大量合并的 Pull Request。以仓库根目录的 CHANGELOG.md 为例单个版本小节下会列出 Backward Incompatible Change向后不兼容变更、New Feature、Performance Improvement、Bug Fix 等多个类别每条条目都对应一个 PR。条目数量庞大用户尤其是数据库管理员和数据工程师往往靠快速浏览 changelog 来判断这个版本升级后会影响什么、有什么新能力可用。因此官方指南开篇即强调Good changelog entries help users quickly understand whats new and how it affects them. We ask contributors to fill out a user-readable changelog entry that will go into the changelog of each release.好的 changelog 条目能帮助用户快速了解新变化及其影响。我们要求贡献者为每个 PR 填写一条用户可读的 changelog 条目它会进入每个版本的 changelog。从仓库源码看changelog 条目并非只在发布时手工整理而是由自动化流水线驱动仓库为贡献者提供 PR 模板 .github/PULL_REQUEST_TEMPLATE.md模板中明确包含Changelog category下拉选择一个类别和Changelog entry填写用户可读的短描述两个字段CI 通过 tests/ci/changelog.py 解析 PR 描述中的这两个字段自动生成 Markdown 格式的 changelog每晚的 CI 任务 ci/jobs/changelog_nightly.py 会基于 master 上合并的 PR 生成原始条目块再由维护者编辑、整理后合并入正式 changelog最终成果按版本归档在 docs/changelogs/ 目录例如v25.12.6.38-stable.md并汇总进 CHANGELOG.md。也就是说你写的每条 changelog 条目都会在无人手工重写的情况下直接进入面向全球用户的发布日志。这就是官方对条目质量提出明确要求的原因。核心原则一以用户为中心而非以开发者为中心指南第一条原则是 Write with the user in mind, not the developer。changelog 条目面向的是用户而不是开发者因此在条件允许时不要只写什么变了what还要解释为什么对用户有用或如何影响用户why / how。官方给出的正反示例非常直观反面示例只陈述了变更本身Addssystem.iceberg_historytable正面示例说明了用户能获得的能力Users can now view historical snapshots of Iceberg tables using the newsystem.iceberg_historytable.用户现在可以使用新的system.iceberg_history表查看 Iceberg 表的历史快照。再看一组关于数据质量检测函数的对比反面示例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.你现在可以使用新的stringBytesUniq和stringBytesEntropy函数检测字符串中可能被加密或随机的数据帮助识别数据质量问题或安全风险。对比可见正面写法把新增两张系统表 / 两个函数翻译成了用户现在可以做什么、得到什么价值。从 CHANGELOG.md 中的真实条目也能印证这一风格例如对system.statements表的描述明确写到该表exposes the documentation of SQL statements——把抽象的表名落到了用户可感知的用途上。核心原则二保持简洁Keep it simple指南要求避免用户不借助解释就无法理解的技术术语长度控制在15 个句子鼓励使用 LLM 辅助检查拼写、语法错误或把条目改写得更友好官方原文甚至俏皮地补了一句 its not cheating, I promise!。官方示例对比反面示例术语堆砌Support correlated subqueries as an argument ofEXISTSexpression正面示例用户能理解的表述You can now use subqueries that reference outer query columns withinEXISTSclauses.你现在可以在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.允许在单查询级别调整 page cache 设置。这对于更快地做实验以及为高吞吐、低延迟查询进行精细调优是必要的。注意这个范本的结构第一句说明功能是什么第二句说明为什么需要。这种是什么 为什么的组合正是下一条格式原则所要求的。格式规则让条目具备统一的阅读体验指南将格式要求归纳为三条每条都配有正反示例易于对照执行。1. 使用完整句子且采用现在时条目必须写成完整的句子而不是名词短语或电报体动词使用现在时一般现在时描述行为。反面示例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开头。这一约定与生成脚本 tests/ci/changelog.py 的规范化逻辑互相呼应——脚本会对小写开头的条目自动大写首字母并确保条目以句号结尾见 tests/ci/changelog.py 附近的entry[0].upper()与补句号逻辑。2. 在必要处使用反引号凡是在clickhouse-client中会输入的内容——设置项、函数名、SQL 语句、格式名、数据类型——都应使用反引号包裹这能让 changelog 条目更易读、代码元素更醒目。反面示例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反引号将use_skip_indexes_if_final、use_skip_indexes_if_final_exact_mode、True这些标识符与普通叙述文本清晰区分方便用户以及搜索引擎和 Agent精准识别代码元素。3. 尽量保持一致的格式指南建议所有条目遵循统一的三段式结构使条目可快速扫读、结构可预测它做什么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 模板与生成脚本共同约束PR 模板 .github/PULL_REQUEST_TEMPLATE.md 要求作者从以下类别中选择一项New FeatureExperimental FeatureImprovementPerformance ImprovementBackward Incompatible ChangeBuild/Testing/Packaging ImprovementDocumentationchangelog entry is not requiredCritical Bug Fixcrash, data loss, RBACBug Fixuser-visible misbehavior in an official stable releaseCI Fix or Improvementchangelog entry is not requiredNot for changelogchangelog entry is not required生成脚本 tests/ci/changelog.py 中定义了categories_preferred_order它既是 changelog 中类别的输出顺序也用于归一化类别名称。脚本对 PR 中填写的类别做规范化匹配忽略大小写、压缩空白并采用归一化 Levenshtein 距离不超过 20% 的模糊匹配见_match_changelog_category从而容忍拼写变体Critical Bug Fix 会被归一化到 Bug Fix (user-visible misbehavior in an official stable release)。与此同时_match_skip_category会把 Documentation、Not for changelog、CI Fix or Improvement 等不需要 changelog 条目的类别过滤掉这正是 PR 模板中标注 changelog entry is not required 的类别。PR 描述解析规则这决定了你的字段写在哪generate_descriptiontests/ci/changelog.py会从 PR body 中提取 category 与 entry按行扫描通过正则识别形如Changelog category:与Changelog entry:的标题行并支持标题与内容同行或标题独占一行、内容在下一行两种写法连续的非空行会被合并为一条 entry中间只允许出现一个空行分隔自动去除 entry 开头的多余项目符号-/*小写开头时自动大写首字母末尾缺少句号时自动补#对 backport 分支backport/前缀的 PR 会回溯到原 PR 提取内容并自动追加 Backported in #NNNN: 前缀dependabot[bot]等机器人作者的 PR 会被直接跳过。理解这些解析规则的意义在于只要你在 PR 模板的对应字段中认真填写脚本就能稳定地抽取出来反之若 category 或 entry 缺失脚本会以 NO CL CATEGORY / NO CL ENTRY 兜底标记让维护者一眼看出需要修正。条目如何进入最终 changelogwrite_changelogtests/ci/changelog.py按categories_preferred_order的顺序输出各大类每条以* entry #PR (author).的 Markdown 列表格式落盘并自动把裸写的 issue 号如#12345转换为 issue 链接。随后ci/jobs/changelog_nightly.py 会每天在auto/changelog-X.Y分支上调用该脚本生成原始条目块维护者再按.claude/skills/edit-changelog/SKILL.md的技能说明进行编辑去重最终合并进 CHANGELOG.md 并按版本归档到 docs/changelogs/。如果你想在本地预览某两个 tag 之间的 changelog仓库还提供了便捷的包装脚本 utils/changelog/changelog.py它会转发调用tests/ci/changelog.py并透传命令行参数如--output、--jobs、--gh-user-or-token。实战自检清单写一条合格的 ClickHouse changelog 条目把官方指南与仓库源码结合起来写一条条目时可以按以下清单自检受众正确读这条日志的是用户不是协作者——他们关心升级后我能做什么而不是我改了什么内部实现信息完整尽量覆盖做什么 → 为什么重要 → 怎么用三段式至少包含前两段简洁控制在 15 个句子避免需要查文档才懂的术语语法规范完整句子、现在时、动词开头如Fixes、Adds、You can now...代码元素加反引号设置项、函数名、SQL 语句、格式名、数据类型等一律用反引号包裹填写位置正确在 .github/PULL_REQUEST_TEMPLATE.md 的Changelog category与Changelog entry字段中填写类别从给定列表选择这样tests/ci/changelog.py才能正确解析。最后再对照官方范本看一条完整示例向量搜索过滤示例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.这条条目同时满足了以用户为中心、简洁、现在时完整句、反引号包裹代码元素、三段式结构全部要求是撰写新条目时最值得模仿的模板。【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考