为发布说明添加变更信息

许多 BeeWare 工具都使用 towncrier 来帮助编写版本发布说明。当您向相关工具提交拉取请求时，需要包含变更说明——该变更说明将成为发行说明中描述变更的条目。

每个拉取请求（PR）都必须在 changes/ 目录中包含至少一个文件，对拉取请求中的变更进行简短描述。变更说明应采用 Markdown 格式，文件名应为 <id>.<片段类型>.md。如果你提出的变更将修复一个已有工单编号的问题或实现一个已有工单编号的功能，ID 就是该工单编号。如果变更没有对应的工单，则可以使用 PR 编号作为 ID。在推送拉取请求之前，您不会知道 PR 编号，因此第一次 CI 通过时，towncrier 检查会失败；添加变更注释并推送 PR 更新后，CI 才应该会通过。

有五种变更片段类型：

• feature：拉取请求（PR）增加了以前不可能的新行为或功能（例如，增加了对新包装格式的支持，或在现有包装格式中增加了新功能）；
• bugfix：该 PR 修复了现有实现中的一个错误；
• doc：PR 是对文档的重大改进；
• removal； PR 代表 BeeWare API 向后不兼容的更改；或
• misc; 不需要在发布说明中公布的细微或管理性变更（如修正错字、细微的语言澄清或更新依赖版本）。

变更说明中的描述应从用户角度出发，使用“营销”的方式总结变更，且不包含深层次的技术描述或实现细节。它有别于提交信息（commit message）——提交信息丛“以便未来的开发人员了解变更的原因”的角度描述了所做的工作；而变更说则直接描述了对用户的好处，因为用户可能并不了解内部知识。

例如，如果你修复了一个与项目命名有关的问题，那么提交信息可能会写成这样：

Apply stronger regular expression check to disallow project names that begin with digits.\ \ （应用更强的正则表达式以禁用任何以数字开始的项目名称。）

相应的变更说明内容如下：

Project names can no longer begin with a number.\ \ （项目名称不能再以数字开头。）

有些 PR 会引入多个功能并修复多个错误，或者引入多个向后不兼容的变更。在这种情况下，PR 可以包括多个变更说明片段。如果需要将两个片段类型与同一个工单编号关联，可以在文件名中添加一个数字后缀。例如，如果 PR #789 添加了工单 #123 所描述的功能，修复了工单 #234 所描述的错误，还做了两项向后不兼容的更改，那么 PR 中就会有 4 个变更说明文件：

• 123.feature.md
• 234.bugfix.md
• 789.removal.1.md
• 789.removal.2.md

有关 towncrier 和片段类型的更多信息，请参阅新闻片段节。你还可以在 BeeWare 仓库的 changes 目录中查看现有的变更片段示例。如果该文件夹是空的，很可能是因为 BeeWare 刚刚发布了新版本；每次发布版本时，towncrier 都会删除变更说明文件，并将它们的内容合并为版本发布说明。您可以查看该文件，了解变更说明所需的编写格式；也可以查看最近合并的拉取请求 ，了解变更说明的格式。