编写变更日志

当发布一个 NPM 包时，最普遍的做法是带上一个 CHANGELOG.md 文件，该文件记录了问题修复、新功能、功能变动或移除。Rush 中可以使用 rush change 来自动完成这些功能。当你准备提交 PR 时，并将变动 commit 到相应的分支上后，需要执行这个命令，它会分析当前分支中的变动，并在必要时让你对其变动进行描述。

如何组织你的描述是很重要的：不能太具体，也不能太复杂，不能暴露隐私，同时要让描述信息更友好。我们建议在可读性上做文章，问问你自己：

• “此次变更是否与第三方开发者有关？”
• “是否存在破坏性变更？”
• “是否修复了某个让人不悦的 bug? ”
• “是否有需要他人适用的新功能？”

在一些工作流中，发布前需要有人来编辑变更日志，然而应该是每个人都尽其最大努力来保证日志内容的清晰和专业。

最佳实践

• 使用 简单的现代时 和 命令式语气。

• 从一个不熟悉项目细节的外部人员的角度来写。

• 尽量描述场景（例如：“搜索现在支持通配符”），而不是代码的变更（例如：“在 SearchHelper 类中增加正则表达式的支持”）

• 使用动词开头，推荐使用：

  • Add - 当你引入或暴露一个新功能、属性、类、UI 等。
  • Remove - 当你完全移除了不会再被使用的东西。
  • Deprecate - 当你计划移除某些东西，但是目前仍然可用。
  • Fix an issue with/where... - 当你修复一个 bug.
  • Improve - 改进了一个已有的东西。
  • Update - 更新了某项东西，但不一定使其更好。
  • Upgrade - 升级了依赖包的版本。
  • Initial/Beta release of ... - 发布了一个新功能。

• 别用 bug 一词，转而使用 issue.

• 不要使用缩写，除非是被广泛认可的（例如："HTTP"）

• 使用正确的拼写和语法。CHANGELOG.md 是发布文档的一部分。

• 当涉及到公共 API 变化时，使用 () 后缀来指出函数名，例如 setSomethingOnWebpart().

• 当涉及到公共 API 变化时，使用 (` `) 来包裹类和其属性名。

• 当描述版本升级时，表明旧版本和新版本，例如："Upgraded widget-library from 1.0.2 to 2.0.1".

• 当修复一个 Github issue 后，考虑在括号中添加 issue URL.

• 不要在句尾添加句号，除非你有两个以上句子。

变更日志消息示例

这里有一些用于编写 rush change 变更日志的示例：

• Add "buttonColor" to the button manifest schema
• Remove support for older mobile web browsers as described in the README.md
• Deprecate the doSomething() API function. Use doSomethingBetter() instead.
• Fix an issue where "ExampleWidget" API did not handle dates correctly
• Improve the diagnostic logging when running in advanced mode
• Upgrade from React 15 to React 16
• Initial release of the flexible panels feature