ClickHouse 更新日志条目编写指南从 PR 描述到发布 Changelog 的完整规范【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse这篇指南围绕 ClickHouse 官方文档《更新日志条目编写指南》展开系统讲解贡献者应当如何为每一个 Pull Request 撰写面向用户、便于阅读的更新日志条目。你将掌握条目写作的用户视角原则、简洁性要求、句子时态与反引号等格式规范并了解这些条目在仓库 CI 校验pr_body_check.py、版本更新日志生成tests/ci/changelog.py以及 docs/changelogs 发布文件中的完整流转链路从而提交符合 ClickHouse 社区标准的 PR。更新日志条目是什么为什么重要ClickHouse 每个版本的更新日志Changelog不是人工堆砌的而是从合并到仓库的每一个 PR 描述中自动提取出来的。在提交 PR 时贡献者需要在 PR 描述里填写两条关键信息Changelog category变更类别和Changelog entry变更条目。合并后CI 工具会解析这些字段按照类别汇总最终生成如docs/changelogs目录下v24.8.14.39-lts.md、v25.11.8.25-stable.md这类版本更新日志文件。因此条目质量直接决定用户能否快速理解每次发布带来了什么。官方指南的第一句话就点明了目标优秀的更新日志条目能帮助用户快速了解有哪些新内容以及这些变化会对他们产生什么影响。这一要求不是可选的CI 中的 pr_body_check.py 会校验 PR 描述是否包含合法的 Changelog entry缺失或内容为空例如只写了...或Close #12345都会直接报错拒绝合并同时该脚本还会校验条目中产品名是否规范拼写为ClickHouse。原则一从用户角度出发而不是从开发者角度出发更新日志条目的读者是使用 ClickHouse 的用户而不只是参与开发的工程师。撰写条目时在合适的情况下尽量不仅说明变更了什么还要说明这项变更为什么对用户有帮助或者会如何影响用户。官方文档给出的正反例对比非常直观不推荐只罗列内部事实新增system.iceberg_history表推荐说明用户能做什么用户现在可以通过新的system.iceberg_history表查看 Iceberg 表的历史快照。再看一个函数类变更的例子不推荐添加stringBytesUniq和stringBytesEntropy函数用于搜索可能为随机或加密的数据。推荐现在您可以使用新的stringBytesUniq和stringBytesEntropy函数检测字符串中可能经过加密或随机生成的数据从而帮助识别数据质量问题或安全隐患。两个例子的共同点是后者把新增了什么翻译成了用户能借此解决什么问题。同样的信息读者的理解成本完全不同。原则二保持简洁避免使用用户在没有解释的情况下可能看不懂的技术术语。条目尽量控制在1–5 句话内。官方指南甚至明确鼓励使用 LLM 帮助检查拼写错误、语法问题或把条目改写得更易于用户理解——这不算作弊。不推荐堆砌内部术语支持将关联子查询用作EXISTSexpression 的参数推荐用用户能理解的方式描述您现在可以在EXISTS子句中使用引用外层查询列的子查询。一个清晰、简洁的典范条目允许按查询级别调整页缓存设置。这对于更快地进行实验以及针对高吞吐、低延迟查询进行微调非常必要。注意这句的结构先陈述能力按查询级别调整页缓存设置再说明价值便于实验和高吞吐/低延迟微调。这种能力 价值的组合正是简洁条目的理想形态。原则三遵循几条简单的格式规范格式规范决定了更新日志在最终渲染后的可读性和一致性。官方指南给出了三条具体要求。使用完整句子并使用一般现在时条目应当是一个完整、独立的句子且统一使用一般现在时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.这一要求在自动化工具中也有呼应tests/ci/changelog.py 在生成条目时会自动为条目末尾补上英文句号.并保证条目的首字母大写仅大写首字母避免破坏 URL 和标识符让每条记录都以规范的完整句形式进入更新日志。必要时使用反引号对配置项、函数名、SQL 语句、格式名称和数据类型等代码元素加上反引号backticks。官方给出的判断标准非常实用凡是你会输入到 ClickHouse 客户端中的内容都应该加上反引号。这样可以让更新日志条目更易读也能避免歧义。不推荐裸写配置名配置项 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尽量保持统一的格式尽量使用相同的结构来组织每一条目推荐的模板是它做了什么 → 为什么这对用户很重要 → 如何使用如有需要统一的格式让读者能更快地浏览更新日志也更容易预期每一条的写法。官方示例你现在可以在向量搜索前或后对结果应用过滤器从而更好地权衡性能与准确性。使用新的vector_search_filter_mode设置来选择你偏好的方式。这条目完美套用了三段式结构能力可以在搜索前后应用过滤器→ 价值权衡性能与准确性→ 使用方式vector_search_filter_mode设置。在 PR 描述中如何填写模板与类别实际提交 PR 时条目填写在 PR 描述body中。.github/PULL_REQUEST_TEMPLATE.md 提供了标准模板其中### Changelog category一节列出了所有可选类别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而### Changelog entry一节则要求填写面向用户的可读短描述模板中直接链接到本文所依据的编写指南。值得注意的是类别与最终更新日志的关系Documentation、CI Fix or Improvement、Not for changelog三类不需要条目也不会出现在更新日志中。这一点在生成工具 tests/ci/changelog.py 中有明确的跳过逻辑_SKIP_CATEGORIES并通过归一化 Levenshtein 距离阈值 20%做模糊匹配来识别这些不进入更新日志的类别。条目在 CI 中如何被校验ci/jobs/scripts/workflow_hooks/pr_body_check.py 是 PR 合并前的最后一道关卡其check_changelog_entry函数主要做三件事解析条目按行扫描 PR 描述识别Short description或Changelog entry开头的行收集其后所有连续行作为条目正文允许多行允许标题与正文之间空一行。拒绝占位内容去掉#*_.-等符号后条目为空、或者条目形如Close #12345仅引用 issue 编号都会被拒绝报错Changelog entry required for category ...。拼写校验通过check_clickhouse_spelling检查条目中产品名是否为规范拼写ClickHouse不规范拼写会被拒并列出。另外PR 作者为机器人如dependabot[bot]或 PR 属于 release 类型时会跳过更新日志检查。从 PR 合并到版本更新日志生成工具如何处理条目合并后的条目由 tests/ci/changelog.py 汇总生成更新日志该脚本的入口包装位于 utils/changelog/changelog.py供习惯于旧路径的开发者使用。了解生成逻辑有助于你写出机器友好的条目类别解析与标准化generate_description从 PR 描述中解析出 category 与 entrytests/ci/changelog.py并用categories_preferred_order中的偏好顺序Backward Incompatible Change→New Feature→Experimental Feature→Performance Improvement→Improvement→Bug Fix→Build/Testing/Packaging Improvement→Other对类别做精确或模糊匹配归一化。条目自动润色工具会剥离条目开头的多余列表符号、将首字母大写、并在末尾自动补上句号——所以你不需要在条目中手工加结尾标点。backport 标注若 PR 是 backport 分支backport/前缀工具会追溯原始 PR并在条目中自动加入Backported in #编号: ...前缀。链接与署名条目中的 issue 编号#12345形式会被自动转换为指向对应 issue 的链接每条最终以* entry #PR号 (作者).的形式写入更新日志并按 PR 编号排序。最终产物就是 docs/changelogs 下按版本命名的 Markdown 文件。你可以打开任意一个近期版本例如v25.11.8.25-stable.md对照阅读观察其中的条目如何体现本文所述的用户视角 简洁 统一格式原则。总结写条目前的快速自查清单面向用户这条变更让用户能做什么解决了用户的什么问题保持简洁控制在 1–5 句话去掉只有开发者才懂的术语。一般现在时 完整句读起来像对当前版本的客观陈述。该加反引号就加配置项、函数名、SQL、格式名、数据类型等凡是会输入客户端的内容都用反引号包裹。统一结构做了什么 → 为什么重要 → 如何使用如有需要。类别合法从 .github/PULL_REQUEST_TEMPLATE.md 的类别列表中选择不需要进入更新日志的类别会由 CI 自动跳过。遵循以上规范你的 PR 描述既能顺利通过 CI 校验其条目也会以清晰、专业的形态出现在 ClickHouse 的版本更新日志中被全球用户快速理解。【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考