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.两者的差别在于反例只陈述了「我们加了什么」正例则把落点放在「用户现在能用它做什么、解决了什么场景问题」上。这正是本指南反复强调的以用户为中心的写作视角。保持简单15 句话避免术语堆砌指南要求条目力求简单避免用户不假解释就无法理解的 jargon长度控制在15 句话之间。同时指南明确鼓励使用 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 FeatureExperimental FeatureImprovementPerformance ImprovementBackward Incompatible ChangeBuild/Testing/Packaging ImprovementDocumentation无需 changelog 条目Critical Bug Fix崩溃、数据丢失、RBACBug Fix官方稳定版中用户可见的错误行为CI Fix or Improvement无需 changelog 条目Not for changelog无需 changelog 条目填写 changelog entry模板中明确要求填写「用户可读的简短描述」并直接链接到本文所依据的编写指南 docs/changelog_entry_guidelines.md。第二步CI 脚本解析 PR 并自动生成 changelogPR 合并后tests/ci/changelog.py 负责生成原始 changelog。这个脚本体现了指南规范如何被工程化执行分类的规范化与排序脚本定义了categories_preferred_orderBackward 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」而没有说明用户能获得什么长度是否控制在 15 句话能用一句话说清的就不要写三句。时态是否用了完整句子 现在时Fixes、Adds、You can now ...反引号设置项、函数名、SQL、格式名、数据类型是否都已用反引号包裹结构是否遵循「做什么 → 为什么重要 → 怎么用可选」分类PR 描述中的Changelog category是否选择了与改动性质匹配的分类避免Not for changelog被误选导致条目静默丢失格式条目是否是单段落的可读文字而不是列表、代码块或零散短语CI 会把它渲染为* 条目 (#PR) (作者).的条目行。遵循这套规范写出的条目既能被用户在 docs/changelogs/ 中快速理解和采纳也能被 tests/ci/changelog.py 正确解析、分类与收录最终完整、准确地呈现在 ClickHouse 每个版本的发布说明中。【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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.两者的差别在于反例只陈述了「我们加了什么」正例则把落点放在「用户现在能用它做什么、解决了什么场景问题」上。这正是本指南反复强调的以用户为中心的写作视角。保持简单15 句话避免术语堆砌指南要求条目力求简单避免用户不假解释就无法理解的 jargon长度控制在15 句话之间。同时指南明确鼓励使用 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 FeatureExperimental FeatureImprovementPerformance ImprovementBackward Incompatible ChangeBuild/Testing/Packaging ImprovementDocumentation无需 changelog 条目Critical Bug Fix崩溃、数据丢失、RBACBug Fix官方稳定版中用户可见的错误行为CI Fix or Improvement无需 changelog 条目Not for changelog无需 changelog 条目填写 changelog entry模板中明确要求填写「用户可读的简短描述」并直接链接到本文所依据的编写指南 docs/changelog_entry_guidelines.md。第二步CI 脚本解析 PR 并自动生成 changelogPR 合并后tests/ci/changelog.py 负责生成原始 changelog。这个脚本体现了指南规范如何被工程化执行分类的规范化与排序脚本定义了categories_preferred_orderBackward 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」而没有说明用户能获得什么长度是否控制在 15 句话能用一句话说清的就不要写三句。时态是否用了完整句子 现在时Fixes、Adds、You can now ...反引号设置项、函数名、SQL、格式名、数据类型是否都已用反引号包裹结构是否遵循「做什么 → 为什么重要 → 怎么用可选」分类PR 描述中的Changelog category是否选择了与改动性质匹配的分类避免Not for changelog被误选导致条目静默丢失格式条目是否是单段落的可读文字而不是列表、代码块或零散短语CI 会把它渲染为* 条目 (#PR) (作者).的条目行。遵循这套规范写出的条目既能被用户在 docs/changelogs/ 中快速理解和采纳也能被 tests/ci/changelog.py 正确解析、分类与收录最终完整、准确地呈现在 ClickHouse 每个版本的发布说明中。【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考