Changelog category (leave one):

Changelog category (leave one):【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouseNew FeatureExperimental FeatureImprovementPerformance ImprovementBackward Incompatible ChangeBuild/Testing/Packaging ImprovementDocumentation (changelog entry is not required)Critical Bug Fix (crash, data loss, RBAC)Bug Fix (user-visible misbehavior in an official stable release)CI Fix or Improvement (changelog entry is not required)Not for changelog (changelog entry is not required)Changelog entry (a user-readable short description of the changes that goes into CHANGELOG.md):...规则是**只保留一个类别删掉其余列表项并在所选类别要求时撰写 changelog 条目**。标注 changelog entry is not required 的三个类别Documentation、CI Fix or Improvement、Not for changelog可以跳过条目这一免条目类别集合与 CI 侧 [pr_labels_and_category.py](https://link.gitcode.com/i/96d92faae7e97d6d1352d770dac50eeb) 中 NO_CHANGELOG_REQUIRED_LABELSpr-not-for-changelog、pr-ci、pr-documentation 等的定义是一致的模板类别字符串与脚本中 LABEL_CATEGORIES 的映射表逐字对应说明模板选项就是 CI 解析的输入契约。 ### 一份优秀正文的完整示例 技能文档引用了官方仓库 PR #96110 的正文作为标杆其中 changelog 条目部分完整如下Changelog category (leave one):Backward Incompatible ChangeChangelog entry:The semantics of thedo_not_merge_across_partitions_select_finalsetting were made more obvious. Previously, the feature could be automatically enabled when the setting was not explicitly set in the configs. It caused confusion repeatedly and, unfortunately, led to some issues in production. Now, the rules are simpler:do_not_merge_across_partitions_select_final1enables the functionality unconditionally. Ifdo_not_merge_across_partitions_select_final0, then automatic is used only if the new settingenable_automatic_decision_for_merging_across_partitions_for_final1and not used otherwise. To preserve the old behaviour as much as possible, the defaults were set todo_not_merge_across_partitions_select_final0andenable_automatic_decision_for_merging_across_partitions_for_final1.The backward-incompatible part is that if someone hasdo_not_merge_across_partitions_select_final0explicitly set in the configs, it no longer protects against the use of automatics. Im open to discussion on whether we should conservatively default to disabled automatics.这个示例值得逐点拆解 - 条目完整讲清了三件事**旧行为**未显式配置时功能可能被自动开启、**新行为**显式 1/0 的语义、新设置的作用条件、**默认值选择**如何尽量保留旧行为 - 分隔线 --- 之后还有补充讨论——这是合法的审阅者看得到但**只有空行之前的 changelog 条目会进入 CHANGELOG** - 结尾主动邀请讨论不兼容点的处理方式体现了写出来供决策的姿态。 ## Changelog 条目写给升级用户不是写给开发者 技能文档对 changelog 条目的核心定位是**它是最终进入公开发布 CHANGELOG 的内容要写给正在升级、正在扫描哪些变更与己有关的用户看**。PR 链接与作者署名由工具自动追加不要手写。 ### 解析格式CI 实际如何截取你的条目 技能文档声称条目收集逻辑位于 [tests/ci/changelog.py](https://link.gitcode.com/i/878ede2ade0ce188084a28fc40190836)这一点可以在源码中得到验证Description.parse 相关的解析逻辑见 [tests/ci/changelog.py#L325-L398](https://link.gitcode.com/i/878ede2ade0ce188084a28fc40190836#L325-L398) python # All following lines until empty one are the changelog entry. while i len(lines) and lines[i]: entry_lines.append(lines[i]) i 1 entry .join(entry_lines)据此可以确认文档所述格式规则脚本从### Changelog entry:或Short description等变体正则还容忍#、、*、_前缀和加粗标记表头之后开始收集直到第一个空行为止收集到的多行用空格 join 成一个段落字符串——所以模板里条目可以跨多行最终变成单段空行会终止收集空行之后的一切如---后的补充讨论被忽略。此外源码还揭示了几个文档未明说、但对撰写者有用的自动规整行为开头的-/*项目符号会被剥掉tests/ci/changelog.py#L391-L393首字母小写会被自动大写末尾缺句号会被自动补上.tests/ci/changelog.py#L435-L437若条目为空类别会被标记为NO CL ENTRY条目退化为NO CL ENTRY: PR标题——即漏写条目的 PR 会以 PR 标题代替条目出现在 CHANGELOG 中而代码注释表明这种情况本应被 CI 的描述检查拦住。由此得到的撰写结论与文档一致把条目写成一个段落——不用项目列表、段内不留空行若要在条目后补充讨论用空行或---隔开。时态、长度、具体性时态混用完全可以且自然。Added X、Fix a case where...、The X setting is now Y都是真实 CHANGELOG 中的写法不必强行统一现在时。长度与影响面匹配。一个新的小函数可以一句话改默认值或向后不兼容的行为需要多少句就写多少句包括用户要做什么来适配。具体性永远点名具体改了什么。绝不写Fix a bug或Improve performance而不说具体对象。文档给出的四个真实 CHANGELOG 范例按影响面从低到高排列是极佳的长度标尺聚焦新增一句话足够Addxxh3_128hashing function.一句话但带足上下文DATEcolumns from PostgreSQL are now inferred asDate32in ClickHouse (in previous versions they were inferred asDate, which led to overflow of values outside a narrow range). Allow insertingDate32values back to PostgreSQL.默认值变更附完整迁移说明Deduplication is turned ON for all inserts by default. It was OFF before for async inserts and for MVs, but it was ON for sync inserts. The goal is to have the same defaults for both ways of inserts. If you have deduplication explicitly disabled on your cluster, you have to explicitly setdeduplicate_insertbackward_compatible_choiceto keep the old behavior.新能力说明细到用户能判断何时该用它AddedOPTIMIZE table DRY RUN PARTS part namesquery to simulate merges without committing the result part. It may be useful for testing purposes: verifying merge correctness in the new version, deterministically reproducing merge-related bugs, and reliably benchmarking merge performance.另一条硬性规则对向后不兼容变更必须同时说明旧行为、新行为、以及如何在可能时恢复旧行为上面do_not_merge_across_partitions_select_final的完整示例就是这一规则的标准执行。如果存在对应 issue在条目末尾引用Closes #XXXXX或Fixes #XXXXX。值得补充的是仓库还有一份面向更广受众的条目写作指南 docs/changelog_entry_guidelines.md其要求与技能文档高度互补以用户而非开发者为第一读者不只说what还说why/howit affects the user、控制在 1–5 句、用反引号包裹设置名/函数名/SQL/格式名/数据类型、遵循它做什么 → 为什么对用户重要 → 如何如需使用的可扫读格式。技能文档与这份指南结合使用基本覆盖了条目撰写的所有维度。类别选择如何驱动 CI 行为从源码结构看changelog 类别不只是发布说明的分组标签它还直接驱动 CI 流水线。pr_labels_and_category.py 中维护了类别到 label 的双向映射LABEL_CATEGORIES/CATEGORY_TO_LABEL例如Backward Incompatible Change→pr-backward-incompatibleCritical Bug Fix (crash, data loss, RBAC) or LOGICAL_ERROR→pr-critical-bugfix该 label 还出现在AUTO_BACKPORT集合中意味着关键修复可触发自动 backport 流程Not for changelog (changelog entry is not required)→pr-not-for-changelogDocumentation (changelog entry is not required)→pr-documentation同时NO_CHANGELOG_REQUIRED_LABELS集合明确列出无需 changelog 条目的类别pr-not-for-changelog、pr-ci、pr-documentation与pr-autogenerated-docs。脚本还实现了基于 Levenshtein 距离的模糊匹配_levenshtein函数用于容错匹配模板中的类别措辞变体——这意味着类别字符串尽量与 模板 原文逐字一致是最稳妥的做法但不要指望大致相似总能被正确识别。在 tests/ci/changelog.py 一侧类别解析还有两个可确认的行为Bug fix类类别会被归一化为Bug Fix (user-visible misbehavior in an official stable release)写入 changelogbackport PR 的条目会被自动加上Backported in #N:前缀。应当避免的写法What to avoid技能文档单列了一节会让 PR 更难读、或传递出低投入信号的模式完整继承如下fix(scope):/feat():/chore():—— ClickHouse 不使用 conventional commits用This PR ...开头任何小节——直接描述改动即可含糊标题Fuzzer fixes、Fix bug、Improvements—— 永远说具体是什么用 Markdown 表格对比改前/改后行为除非确实有用通篇完全平行的句式——自然变换措辞。AI 协作署名与确认偏好技能文档明确表态公开提及 AI 协助是被接受的。commit 中加Co-Authored-By:或在 PR 描述中致谢均可——ClickHouse 对 AI 辅助开发持开放态度。这与仓库内其他 AI 相关设施如 .github/copilot-instructions.md的存在相互印证。关于应用流程创建或更新 PR 前技能会检查用户记忆中是否存有确认偏好若无偏好且会话是交互式的会询问一次是否每次应用前给你过目还是每次直接执行然后把答案存入记忆并长期遵循非交互会话则直接执行、不询问。Fork 与上游PR 必须开在规范仓库上文档最后一节处理 fork 场景如果当前仓库是 fork判断方式git remote get-url origin不包含ClickHouse/ClickHousePR 必须指向上游规范仓库具体做法是给gh pr create传参gh pr create --repo ClickHouse/ClickHouse --head fork-owner:branch【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考