使用发行说明¶
Adjutant 团队使用 reno 来生成发行说明。这些是重要的用户可见文档，必须在执行用户或操作员相关的变更时包含，例如 bug 修复或新功能。发行说明应包含在进行工作的同时提交的补丁中。发行说明应简短、易于阅读和易于维护。它们也必须链接回任何适用的文档（如果存在）。以下约定有助于确保所有发行说明都实现这些目标。
大多数发行说明要么描述 bug 修复，要么宣布对新功能的支持，这两者都使用 Launchpad 进行跟踪。以下约定依赖于 Launchpad 中的链接，为读者提供更多上下文。
警告
我们强烈建议在编写和审查发行说明时仔细考虑。一旦发行说明与正式版本一起发布，在后续版本中更新它会导致它在后续版本中发布。除非在非常特殊的情况下需要，否则应拒绝在它添加的分支之外更新或修改先前版本发行说明的审查。
请参阅 reno 的 文档 以获取更多信息。
Bug 修复的发行说明¶
在创建传达 bug 修复的发行说明时，在发行说明的名称中使用 story 编号
$ tox -e venv reno new story-1652012
Created new notes file in releasenotes/notes/story-1652012-7c53b9702b10084d.yaml
发行说明的正文应清楚地解释该影响将如何影响用户和操作员。它还应包括为什么需要此更改，但不要过于具体地说明实现细节，因为可以在提交和 bug 报告中找到这些细节。它应包含一个在 reStructuredText 中正确格式化的链接，该链接指向用于跟踪修复的原始 bug 报告。这确保了发行说明保持简短和切中要点，同时为读者提供其他资源
---
fixes:
- |
[`bug 1652012 <https://storyboard.openstack.org/#!/story/111111>`_]
This bug was fixed because X and we needed to maintain a certain level
of backwards compatibility with the fix despite so it still defaults to
an unsafe value.
deprecations:
- >
X is now deprecated and should no longer be used. Instead use Y.
Feature 功能的发行说明¶
描述功能工作的发行说明遵循相同的基本格式，因为功能也作为 story 进行跟踪。
$ tox -e venv reno new story-1652012
Created new notes file in releasenotes/notes/story-1652012-7c53b9702b10084d.yaml
就像传达 bug 修复的发行说明一样，描述功能工作的发行说明必须包含一个链接回 story。读者应能够轻松发现实现该功能的所有补丁，以及找到完整的规范和文档链接。发行说明可以添加到功能的最后一个补丁中。所有这些通常可以在 storyboard 上的 story 中找到
---
features:
- >
[`story 1652012 <https://storyboard.openstack.org/#!/story/222222>`_]
We now support Q
upgrade:
- >
We highly recommend people using W to switch to using Q
在极少数情况下，如果发行说明不涉及 bug 或功能工作，请使用合理的 slug 并包含与该说明相关的任何文档。我们可以在审查过程中迭代内容和发行说明的应用。
有关如何以及何时创建发行说明的更多信息，请参阅 project-team-guide。
