撰写变更日志

在发布 NPM 包时，通常的做法是包含一个 CHANGELOG.md 文件，以告知您的用户有关错误修复、新功能以及更改或删除的功能的信息。Rush 使用 rush change 命令来自动执行此操作。此命令应在您准备好合并 PR 后运行，在将所有更改提交到分支后运行。它会分析您分支中的更改，并在（必要时）提示您编写对更改的人类可读描述。

您描述的方式很重要。您不想过于简洁或具体，不想泄露私人信息，并且希望描述尽可能有用。我们建议在可读性方面犯错误。问问自己

• "我的更改对第三方开发者有何意义？"
• "它会破坏他们吗？"
• "它是否修复了困扰他们的错误？"
• "它是否为他们提供了一个新的功能来尝试？"

在某些工作流程中，人类编辑会在发布变更日志之前对其进行审查，但每个人都应该尽力确保内容清晰专业。

推荐实践

• 使用 现在时，使用 祈使语气 ("命令")。

• 从可能不熟悉您包实现细节的外部受众的角度撰写

• 专注于场景结果 ("搜索现在支持通配符") 而不是代码更改 ("在 SearchHelper 类中添加了正则表达式支持")

• 以动词开头。建议使用以下动词

  • **添加** - 当您介绍或公开新功能、属性、类、UI 等时。
  • **移除** - 当您完全删除某项内容且它不再可用时。
  • **弃用** - 当您计划删除某项内容但它仍然可用时。
  • **修复与/在...方面的问题** - 当您修复错误时。
  • **改进** - 当您使现有内容变得更好时。
  • **更新** - 当您刷新某项内容但没有使其变得更好时。
  • **升级** - 当升级依赖项的版本时。
  • **... 的初始/测试版发布** - 当发布一项全新的功能时。

• 不要使用 **bug** 这个词。使用 **问题** 代替。

• 不要使用缩写词或首字母缩略词，除非它们被广泛认可（例如，“HTTP”）

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

• 在引用公共 API 更改时，使用 () 后缀来指示函数名称，例如 setSomethingOnWebpart()

• 在引用公共 API 更改时，使用反引号 (` `) 围绕类和属性名称。

• 在记录升级时，请指出旧版本和新版本。例如："将 widget-library 从 1.0.2 升级到 2.0.1"

• 如果修复了 GitHub 问题，请考虑在括号中添加问题 URL。

• 除非您有两个或多个句子，否则不要添加尾随句号。

示例变更日志消息

以下是一些可能提供给 rush change 的假设变更日志消息

• 在按钮清单模式中添加 "buttonColor"
• 删除对 README.md 中所述的旧版移动 Web 浏览器的支持
• 弃用 doSomething() API 函数。使用 doSomethingBetter() 代替。
• 修复 "ExampleWidget" API 在处理日期时出现的问题
• 改进在高级模式下运行时的诊断日志记录
• 从 React 15 升级到 React 16
• 灵活面板功能的初始发布