Release Notes 规范

Posted on Edited on In

Release Notes 作为开源软件工程实践的重要一环，会很大程度上影响用户体验和交付流程。此篇文档是本人在历次发版任务中总结出来的模板规范，用以帮助产研提升 Release Notes 质量。该规范已由组内推广至 PingCAP 全公司。

相关文档

  • Release Notes 填写规范
  • Release Notes 描述规范
  • Development-Documentation Release Notes 加工
  • 官方发布：Release Notes | PingCAP Docs

参考模板

注意：以下模板和规范仅限 PR/ISSUE 粒度，跨大版本发布时所需的详细 release notes 不在本文讨论范围

基本要求

  • 句首字母大写
  • 结尾不出现标点符号
  • 语法正确
  • 祈使句
  • 用户视角
    • Release Notes 的写作参考 PR 对应的 GitHub issue。GitHub issue 是用户侧最直接感知的问题，Release Notes 应就用户侧直接感知的问题进行简要概述，而非对代码侧进行概述。PR 中的提供的 Release Notes 应与 GitHub issue 标题和描述高度一致，避免割裂
    • 不描述具体修改细节，以概述为主
    • 对于 Bug fix notes，强调该条改动对用户的意义，帮助用户解决了什么问题
    • 在编写 Improvements 或 Feature enhancements 部分的 note 时，还需要写出改动为用户带来的好处，或是提升性能，或是增强稳定性，或是更丰富的功能体验
    • 在编写 Bug fix 部分的 note 时，需要写清楚问题触发的条件和问题带来的影响，最好还能写出用户的 workaround
  • 表述完整 & 简洁
  • 变量参数名、配置项名、值、SQL 语句、命令、列类型等用 `` 反引号包括。如果需要表示字符串，也可使用引号 “ 或 ‘
  • 闭源 Repo 结尾不要附 PR 链接
  • SQL 表达式等相关专用单词全字母大写，例如：COUNT DISTINCT；HAVING；STR_TO_DATE；

PR Reviewer 以及 PM 需按照上述原则审核用于对外发布的 Release Notes

  • 由 PR reviewer 审查日常提交的每个 PR 的 release notes、labels
  • PM 需要在发版前，针对 Bug Triage List 中相关 issue 或 PR 再次审核

对于不合规范或有问题的条目需要公布并集体讨论

对于文档组有修改意见的条目需要公布并集体讨论

如果有新的格式可用于规范模板，请及时补充到本文档中

以下为根据历史发版记录总结的部分模板，建议填写 Release Notes 时参考

Compatibility changes

这一部分涵盖了此发版相较于上一发版，所涉及的配置项变更、默认值变更以及所有产生兼容性问题的变更。相对于其他 note，这一部分更容易对线上业务造成影响，是用户需要重点关注的。也是 Release Notes 的重点之一。

Compatibility changes 的 note 需要说明两个信息：

  • 此前的代码行为、配置项、默认值是什么
  • 从此版本起，新的代码行为、新的配置项、新的默认值是什么

Feature enhancements

提升改进或功能增强的 note，开头的动词多为 Support 和 Add

支持/实现 具体功能

  • Support [doing something]
  • Support the […]
  • Add […]
  • 例如：
    • Support casting the STRING type to the DOUBLE type
    • Support the Cartesian join
  • 支持函数下推
    • Support the XXX() function
    • 函数名称全字母大写，最后加上 ()
    • 例如：
      • Support the DATE() function
      • Support the STR_TO_DATE() function

优化功能

  • Optimize the […]
  • 例如：
    • Optimize the non-joined data in right outer join using multiple threads

Bug fixes

开头使用 Fix a […] bug that […] | Fix the […] issue/error/exception that/of […]

不建议使用 may | might 等不确定性字样，可使用 a/the potential […] bug/issue，样例：

  • Fix the issue that TiFlash keeps restarting because of …
  • Fix the potential issue that TiFlash cannot …
  • Fix a bug that TiFlash fails to …

错误/异常相关问题模板

  • Fix the issue of incorrect results that occurs when/during …
  • Fix the issue of wrong query results that occurs when …
  • Fix the issue of unexpected results that occurs …
  • Fix the TiFlash panic issue that occurs when …
  • Fix the potential/occasional panic that occurs when …

修改样例

Compatibility changes

1
copr: cast invalid utf8 string to real bug fix
  • 描述过于简略，表意不完整
  • 该改动涉及用户可感知的代码行为改动，会造成兼容性变化，但是未在 release notes 中体现出来

修改意见

1
Before v4.0.16, when TiDB converts an illegal UTF-8 string to a Real type, an error is reported directly. Starting from v4.0.16, TiDB processes the conversion according to the legal UTF-8 prefix in the string
1
sink: fix kafka max message size inaccurate issue.
  • 描述过于简略，表意不完整
  • 该改动修改了参数默认值，造成兼容性更改，但是未在 release notes 中体现出来

修改意见

1
Change the default value of Kafka Sink max-message-bytes to 1 MB to prevent TiCDC from sending too large messages to Kafka clusters
1
cdc/sink: adjust kafka initialization logic
  • 描述过于简略，表意不完整
  • 该改动修改了参数默认值，造成兼容性更改，但是未在 release notes 中体现出来

修改意见

1
Change the default value of Kafka Sink partition-num to 3 so that TiCDC distributes messages across Kafka partitions more evenly

Feature enhancements

1
Not use the stale read request's `start_ts` to update `max_ts` to avoid commit request keep retrying
  • 该优化的目的和结果是避免 commit 请求重试，方式为不使用 Stale Read 请求的 start_ts 更新 max_ts。应先说目的和结果

修改意见

1
Avoid excessive commit request retrying by not using the Stale Read request's start_ts to update max_ts

Bug fixes

1
fix potential npe in executeTS during DAG compile
  • 首字母非大写
  • executeTS 具体含义指代不清
  • npe 具体含义指代不清
  • 缺乏概述

修改意见

1
Fix the potential panic issue that occurs when running table scan tasks

或

1
Fix the null pointer exception (NPE) that occurs when running table scan tasks
1
Fix Cannot convert NULL value to non-Nullable type error for scalar aggregation with aggregation function count and count distinct
  • 语法不清
  • 格式较乱
  • 描述过多细节，缺乏概述
  • count 和 count distinct 相关 SQL 专用词需要全字母大写。并加上 ``

修改意见

1
Fix the issue of unexpected results when executing the aggregation functions `COUNT` or `COUNT DISTINCT`
1
fix mpp random crash if mpp query meet errors
  • 首字母非大写
  • mpp 指代不清（是否专用词？）
  • 格式不清晰

修改意见

1
Fix the potential crash issue that occurs when executing `MPP` tasks
1
support having in DAG request
  • 首字母非大写
  • having 相关 SQL 专用词格式有误
  • request 语法错误

修改意见

1
Support the `HAVING()` function in DAG requests
1
Fix TiFlash server random crash when deconstruct SharedQueryBlockInputStream
  • 语法/格式有误

修改意见

1
Fix the potential crash issue that occurs when deconstructing `SharedQueryBlockInputStream`
1
fix random terminate without exception error when deconstruct MPPTask
  • 语法/格式有误
  • MPPTask 是否专用词
  • 需精简概述

修改意见

1
Fix the potential panic issue that occurs when deconstructing `MPPTask`
1
retry when meeting stablish conn fails
  • 首字母非大写
  • 语法/格式混乱
  • 表述不清且完整性较差

修改意见

1
Fix the issue of unexpected results when TiFlash failed to establish `MPP` connections
1
fix resolve lock race
  • 所有问题同上

修改意见

1
Fix the potential panic issue that occurs when resolving locks
1
Fix problem CastStringAsInt may produce wrong result
  • 使用内部函数名词，可读性较差
  • 语法/格式有误
  • 不需要使用 may 这类不确定性词句

修改意见

1
Fix the issue of incorrect results when casting string as integer
1
Fix a string compare bug that sometimes >= and <= will return wrong result if the contains with `\0`
  • 语法/格式有误
  • 描述过多细节，缺乏概述
  • 直接使用 \0 对外部表意不清

修改意见

1
Fix the issue of incorrect results when comparing a string that contains zero bytes
1
lock_resolver: avoid pessimistic transactions using resolveLocksForWrite
  • 没有从用户视角出发，未说明解决了什么问题，与 GitHub issue 不一致
  • 描述偏重代码侧细节，缺乏概述，例如 resolveLocksForWrite
  • 未以 Fix the issue 开头，不是标准的 bug fix note

修改意见

1
Fix the issue that committing pessimistic transactions might cause write conflict