数据库OLAP列式数据库大数据实时分析数据分析【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址https://gitcode.com/GitHub_Trending/cli/ClickHouse点击查看免费下载写好 changelog变更日志条目是每一位 ClickHouse 贡献者在提交 Pull RequestPR时的必修课。本指南以 ClickHouse 官方《Changelog entry guidelines》英文原版、西班牙语版为骨架结合仓库中真实的 PR 模板、CI 校验脚本与发布日志生成工具系统讲解以用户为中心的条目撰写原则、格式规范以及一条优秀条目如何从 PR 描述一路进入每个版本的 CHANGELOG.md。读完本文你将能写出专业、清晰、符合 ClickHouse 社区标准且能被 CI 自动校验通过的 changelog 条目。为什么 changelog 条目如此重要ClickHouse 的每个发布版本都会生成一份完整的变更日志存放于 docs/changelogs 目录例如 v25.11.8.25-stable.md。这些日志是数百万用户判断升级后我能得到什么、会遇到什么变化的第一手资料。指南开篇就点明了立场好的 changelog 条目帮助用户快速理解有什么新东西以及这些变化会如何影响他们。因此项目要求每位贡献者在提交 PR 时填写一段面向用户可读的 changelog 条目最终汇入每个版本的发布日志。这不是走过场的流程——它直接决定了发布说明的可读性与质量。原则一以用户为中心而非以开发者为中心指南提出的第一条也是最核心的原则是changelog 条目是用来向用户传达变更的而不仅仅是向开发者。撰写时不仅要说明改了什么what更要说明为什么对用户有用why或如何影响用户how。指南给出的对照示例❌ 只描述改动本身✅ 说明用户价值新增system.iceberg_history表用户现在可以通过新的system.iceberg_history表查看 Iceberg 表的历史快照。新增stringBytesUniq和stringBytesEntropy函数用于搜索可能随机或加密的数据你现在可以使用新的stringBytesUniq和stringBytesEntropy函数检测字符串中潜在加密或随机数据帮助识别数据质量问题或安全隐患。可以看出改写后的条目把新表/新函数翻译成了用户能做什么、解决了什么问题。这正是 ClickHouse 希望每个条目达到的效果读者不必是数据库内核专家也能一眼看懂升级收益。原则二保持简单15 句话指南建议避免用户不查资料就难以理解的技术黑话条目控制在 15 句话之间。更有趣的是官方明确鼓励借助 LLM 帮忙捉错别字、改语法或把条目改写得更用户友好——这不是作弊我保证对照示例❌ 术语化表述✅ 用户友好表述支持将相关子查询作为EXISTS表达式的参数你现在可以在EXISTS子句中使用引用外部查询列的子查询。一个公认清晰简洁的示例允许按查询级别调整页面缓存配置。这是为了更快的实验以及为高吞吐、低延迟查询提供微调的可能性。好的条目应该让读者在 5 秒内完成这是什么 → 我需不需要它的判断。遵循几条简单的格式规范指南将格式要求归纳为四点它们共同保证日志的可读性和可扫描性。1. 使用完整的句子且用现在时条目应该是语法完整的陈述句时态用现在时present tense。❌✅修复了一个崩溃如果在尝试删除临时文件时抛出异常修复了一个在尝试删除临时文件时抛出异常导致的崩溃。修复了Fixes新增了Adds这类现在时动词是日志中的标准开头让读者感觉变更正在进行且当前可用而不是历史叙述。2. 在必要处使用反引号代码元素settings、函数名、SQL 语句、格式名、数据类型等要用反引号包裹。凡是你会输入到clickhouse-client里的内容都应该用反引号。这能显著提升日志的可读性。❌✅Settings use_skip_indexes_if_final 和 use_skip_indexes_if_final_exact_mode 现在默认值为 TrueSettingsuse_skip_indexes_if_final和use_skip_indexes_if_final_exact_mode现在默认值为True在 ClickHouse 源码中这些命名约定随处可见。例如在 tests/ci/changelog.py 的类别定义里正式类别名 Bug Fix (user-visible misbehavior in an official stable release) 这类带括号的长名称被原样保留用于日志排版而在真实日志条目中函数、设置名无一例外都带有反引号如memory_worker_purge_dirty_pages_threshold_ratio、domainRFC见 v25.11.8.25-stable.md。3. 尽量遵循一致的格式推荐格式模板是它做什么 → 为什么对用户重要 → 如何使用如果需要这样写出的条目既容易被扫读也让读者产生预期。指南给出的示例你现在可以在搜索操作之前或之后过滤向量搜索结果从而更好地控制性能与准确率之间的权衡。使用新的vector_search_filter_mode设置选择你喜欢的方式。这个结构做了啥 → 有啥好处 → 怎么配是 ClickHouse 日志中最具代表性的三段式写法。4. 遵循一致格式的工程化落地格式一致不只是文风问题在 ClickHouse 仓库里它被工程化了CI 会用正则表达式从 PR 描述中解析 changelog 条目。解析逻辑在 ci/jobs/scripts/workflow_hooks/pr_body_check.py 中匹配Short description或Changelog entry标题行大小写不敏感容忍#、*、_、等 Markdown 前缀标题后的所有非空行被拼接为条目内容空行被视为条目结束分隔符条目被剥离#*_.-等字符后若为空则校验失败报错Changelog entry required for category ...。因此条目必须紧跟在 Changelog entry 标题之下且中间不要插入与条目无关的空行或额外段落否则解析结果会与预期不符。这一点在 tests/ci/changelog.py 的generate_description中也有镜像实现两处逻辑保持一致。从 PR 模板到发布日志changelog 的完整旅程理解了写作原则后再看一条条目在仓库中的完整流转链路能让你更清楚为什么必须这么写。第一步在 PR 模板中声明类别与条目PR 描述模板 .github/PULL_REQUEST_TEMPLATE.md 明确要求贡献者填写两部分Changelog category选择一个New FeatureExperimental FeatureImprovementPerformance ImprovementBackward Incompatible ChangeBuild/Testing/Packaging ImprovementDocumentationchangelog entry 不是必需的Critical Bug Fixcrash、data loss、RBACBug Fixuser-visible misbehavior in an official stable releaseCI Fix or Improvementchangelog entry 不是必需的Not for changelogchangelog entry 不是必需的**Changelog entry**一段指向本指南的、面向用户的简短描述将进入 CHANGELOG.md。第二步CI 自动校验PR 创建后pr_body_check.py会读取 PR 的标题、正文与标签并执行校验对不需要 changelog 的类别pr-not-for-changelog、pr-ci、pr-documentation、pr-autogenerated-docs定义见 ci/jobs/scripts/workflow_hooks/pr_labels_and_category.py直接放行对需要条目的类别若解析不到有效条目则报错拒绝额外用check_clickhouse_spelling检查条目中的产品名拼写强制规范为ClickHouse错误拼写清单在 ci/jobs/scripts/check_style/clickhouse_spelling_ignore.txt 维护。标签与类别名的映射定义在 pr_labels_and_category.py一个标签可能对应多个历史类别写法例如pr-bugfix同时承认 Bug Fix、Bug Fix (user-visible misbehavior in an official stable release) 等三种措辞这既兼容了旧写法也把拼写不一的类别收敛到统一标签。第三步changelog 脚本按类别生成日志发布时tests/ci/changelog.py 会拉取两个版本标签之间的所有已合并 PR从中提取条目与类别并按固定的类别顺序输出categories_preferred_order ( Backward Incompatible Change, New Feature, Experimental Feature, Performance Improvement, Improvement, Bug Fix (user-visible misbehavior in an official stable release), Build/Testing/Packaging Improvement, Other, )脚本还会自动处理几件事条目润色把条目的首字母大写若条目末尾没有句号则自动补上.条目分类兜底类别匹配不到时归入 NO CL CATEGORY没有条目时归入 NO CL ENTRY机器人作者过滤dependabot[bot]等机器人提交的 PR 不会进入日志跳过规则命中 not-for-changelog 或 CI Fix or Improvement 的 PR 被归入 NOT FOR CHANGELOG / INSIGNIFICANT 段从源码结构看这类条目不会进入正式类别backport 追溯若当前 PR 是 backport 分支backport/开头会追溯到原始 PR并在条目前加上Backported in #NNNN:前缀——这正是 v25.11.8.25-stable.md 中大量条目以 Backported in 开头的来源issue 链接化将裸的 issue 编号4 位以上数字自动转换为链接。日常维护者也可以直接运行 utils/changelog/changelog.py 这个包装脚本它转发到tests/ci/changelog.py通过--from/TO_REF参数指定版本区间生成 Markdown 日志。第四步进入版本发布文档最终条目以* 条目内容 #PR编号 (作者).的格式写入年度 changelog 文件。真实示例来自 v25.11.8.25-stable.md* Backported in #95166: Run purging of jemalloc dirty pages in a different thread from main thread of MemoryWorker. If purging is slow, it could delay updates of RSS usage which could lead to out of memory kills of the process. Introduce new configmemory_worker_purge_total_memory_threshold_ratioto start purging dirty pages based on ratio of total memory usage.这条日志完整践行了本指南的规范现在时完整句子、反引号包裹配置名、讲清改了什么 为什么。快速自检清单提交 PR 前用下面这张清单对照你的 changelog 条目对象是写给用户看还是只写给开发者看把改了 X改写成现在你可以用 X 做 Y。长度15 句话以内不含需要额外解释的术语。时态与完整性完整句子使用现在时Fixes / Adds / Improves ...。反引号所有clickhouse-client中会出现的内容settings、函数名、SQL、格式名、类型都加了反引号。结构遵循做什么 → 为什么重要 → 怎么用的顺序。位置与格式条目紧跟在### Changelog entry标题后中间无空行否则 CI 的解析器可能取到空条目而报错。拼写产品名统一写ClickHouse避免触发 CI 的拼写校验。类别在 PULL_REQUEST_TEMPLATE.md 列出的类别中勾选一个若是 Bug 修复建议使用完整的 Bug Fix (user-visible misbehavior in an official stable release)。结语写好 changelog 条目是 ClickHouse 社区协作文化的一部分它让每次发布说明都成为用户真正能读懂的升级指南而不是一串开发者黑话。遵循以用户为中心、保持简单、遵守格式规范这三条主线再配合仓库中 CI 校验与生成脚本的自动化保障你贡献的每一条变更都能被全球用户准确理解、轻松检索——这正是开源项目高质量文档体系的基石。赞分享数据库OLAP列式数据库大数据实时分析数据分析【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址https://gitcode.com/GitHub_Trending/cli/ClickHouse点击查看免费下载相关推荐ClickHouse Changelog 条目撰写指南从 PR 模板到发布日志的规范与实践ClickHouse Changelog 条目撰写指南从 PR 模板到发布日志的规范与实践 导读 本指南面向 ClickHouse 的贡献者系统讲解如何撰写数据库OLAP列式数据库大数据实时分析数据分析ClickHouse 更新日志条目编写指南从 PR 描述到发布 Changelog 的完整规范ClickHouse 更新日志条目编写指南从 PR 描述到发布 Changelog 的完整规范 这篇指南围绕 ClickHouse 官方文档《更新日志条目编写数据库OLAP列式数据库大数据实时分析数据分析ClickHouse Changelog 条目编写指南从 PR 描述到发布日志的最佳实践ClickHouse Changelog 条目编写指南从 PR 描述到发布日志的最佳实践 本文围绕 ClickHouse 仓库的官方文档 docs/chang数据库OLAP列式数据库大数据实时分析数据分析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考