README¶
OpenStack Nova 规范¶
这个 git 仓库用于存放 Nova 项目的已批准设计规范。规范的评审在 gerrit 中进行，流程类似于我们评审和合并代码本身的流程。关于规范评审的具体政策，请参考本文档末尾。
这个仓库的布局是
specs/<release>/
其中包含两个子目录
- specs/<release>/approved
已批准但尚未实现的规范
- specs/<release>/implemented
已实现规范
这种目录结构允许您了解我们考虑过什么、决定做什么以及实际完成什么。对特定发布的功能感兴趣的用户应该只参考 implemented 目录。
规范的生命周期¶
提出规范的开发者应该在 approved 目录中提出一个新文件。 nova-specs-core 将以 OpenStack 项目的常用方式评审变更，并最终在达成共识后合并。
目前 Launchpad 蓝图也已“定义”批准。开发者可以自由地提出代码评审以实现他们的规范。这些评审应该在提交信息中引用 Launchpad 蓝图，以便跟踪目的。
注意
Launchpad 蓝图的“定义”批准表明 nova-specs-core 团队同意该提案的技术方面（“如果我们要做这个，这就是方法”）。蓝图的“方向”批准是对目标发布的承诺的单独指示（“我们现在想做这个”）。 规范和蓝图可能已获得“定义”批准，但由于后续的规划活动而未获得“方向”批准。在这种情况下，蓝图（以及任何未合并的代码）可能会推迟到未来的发布版本中考虑。
待办事项
记录这些“规划活动”的细节。
一旦功能的全部代码合并到 Nova 中，nova 维护者会将 Launchpad 蓝图标记为“已实现”。
在发布周期结束时，已实现的规范将从 approved 目录移动到 implemented 目录，并创建重定向，以便不会破坏指向已批准规范的现有链接。（重定向不是符号链接，它们是在 sphinx 消耗的文件中定义的。一个例子在 specs/stein/redirects 中。）
我们在每个发布周期的末尾使用 tox -e move-implemented-specs 目标来自动移动已完成的规范并填充该版本的重定向文件。例如
tox -r -e move-implemented-specs -- --dry-run --verbose train
删除 --dry-run 标志以执行实际的文件移动/写入。然后提交更改并像往常一样将评审提交到 gerrit。
示例规范¶
您可以在 specs/<release>-template.rst 中找到给定版本的规范模板。
待办规范¶
此外，我们允许提出没有指定开发者或未针对当前版本发布的规范。这些规范以与上述相同的方式进行评审，但被添加到
specs/backlog/approved
此目录中的规范表明原始作者要么无法提供，要么表示他们将不会实现该规范。这里找到的规范可供希望参与 Nova 的人员作为项目。或者，它们可能是某个发布周期中生成的想法，以开始设计讨论，但并非打算在未来的周期中实现。如果您有兴趣声明一个未分配的待办规范，或者您是分配者并且准备好将其建议用于当前版本的实现，请从发布评审移动规范开始。为了确保现有的链接不会中断，必须以类似于 implemented 规范的流程创建重定向。 move-spec tox 目标可用于帮助完成此操作。例如
tox -e move-spec -- --dry-run --verbose specs/backlog/my-great-idea.rst specs/train/approved
删除 --dry-run 选项以执行实际的文件移动/写入。然后提交更改并像往常一样将评审提交到 gerrit。
注意
请勿使用 move-spec 将未实现规范从一个版本重新提出到另一个版本。而是按照 先前批准的规范 中的说明进行操作
在声明未分配的待办规范时，请将自己设置为新的 主要分配者，并在 其他贡献者 列表中保留原始作者。
放弃规范¶
注意
目前，此过程仅应用于放弃待办规范。请勿将其用于实际发布版本的 approved 目录中的规范。目前，表明某个规范已被放弃的指标是它从未出现在任何版本的 implemented 目录中。我们可能会在未来更改此过程。
如果确定 backlog 规范“永远”不会实现，请发布评审将规范从 specs/<release>/approved 移动到 specs/abandoned。与上述流程类似，必须创建重定向以确保现有的链接不会中断。 abandon-spec tox 目标可用于帮助完成此操作。例如
tox -e abandon-spec -- --dry-run --verbose specs/backlog/it-was-a-great-idea.rst
删除 --dry-run 选项以执行实际的文件移动/写入。
请在规范中添加解释说明放弃的原因，并相应地更新历史记录部分。
Juno 之前的版本的文档¶
在 Juno 开发周期之前，此仓库未用于规范评审。Juno 之前的评审完全通过 Launchpad 蓝图 完成
请注意，Launchpad 蓝图仍然用于跟踪蓝图的当前状态。有关更多信息，请参见 https://wiki.openstack.org/wiki/Blueprints
使用 gerrit 和规范单元测试¶
有关使用 gerrit 的更多信息，请参阅 https://docs.openstack.org/infra/manual/developers.html#development-workflow
为了验证规范在语法上是否正确（即，获得更多 Zuul 结果的信心），请执行以下命令
$ tox
运行 tox 后，文档将以 HTML 格式在 doc/build/html/ 目录中提供以供查看。
规范评审政策¶
nova-specs-core 在评审提出的规范时将应用许多评审政策。它们是
琐碎的规范¶
提出的更改是琐碎的（少量代码）并且不更改任何公共 API，有时不需要提供规范。在这种情况下，Launchpad 蓝图被认为是足够的。这些提案在每周 nova IRC 会议 的 公开讨论 部分中获得批准。如果您认为您提出的功能是琐碎的并且满足这些要求，我们建议您在编写完整的规范之前将其带到那里讨论。
先前批准的规范¶
规范仅针对单个版本批准。如果您的规范先前已批准但未实现（或未完全实现），则必须重新申请规范的批准。您可以重新提出您的规范，方法如下
将您的规范复制（不要移动）到当前版本的正确目录。
更新文档以符合新模板；修改历史记录部分；如果需要，选择一个新的 功能联络人。
如果规范没有功能更改（只有模板更改），则将
Previously-approved: <release>标签添加到您的提交信息中。发送进行审查。
这些规范将受到与任何其他规范相同的评审流程。
依赖于其他 OpenStack 项目合并代码的规范¶
对于依赖于其他 OpenStack 项目中代码合并的规范，我们不会在其他项目的代码合并之前批准 nova 规范。一个很好的例子是 Cinder 和 Neutron 驱动程序。要指示您的规范处于这种状态，请使用 Depends-On git 提交信息标签。正确的格式是 Depends-On: <change id of other work>。nova-specs-core 可以在任何时候批准规范，但它不会合并，直到我们需要在其他项目中着陆的代码也合并为止。
新的 libvirt 镜像后端¶
在某些情况下，作者可能会提出一个新的 libvirt 驱动程序镜像存储后端，该后端不需要其他 OpenStack 项目中的代码。一个例子是 ceph 镜像存储后端，如果我们将它视为与 ceph 卷支持代码分开对待。在 libvirt 驱动程序中实现新的镜像存储后端总是需要规范，因为我们对足够的 CI 测试存在历史担忧。
待办事项
编写关于 nova 团队的角色和责任的详细部分，包括两个 +2 规则、同一公司三法则、+2 规范是否代表承诺评审相应的代码等。
功能联络人常见问题解答¶
在 Ussuri 中，强制性的“功能联络人”部分被添加到规范模板中。本节试图解决围绕此概念的一些问题。在 Victoria 中，我们使填写该部分是可选的，但仍然鼓励贡献者使用它。
- 功能联络人做什么？
通过注册成为规范的功能联络人，您同意帮助引导功能完成开发过程。这取决于规范所有者的身份/角色以及您在项目中的相对角色。一些例子
为经验不足的贡献者担任联络人： 这是联络人概念构思的情况。在这种情况下，联络人的工作是指导规范所有者，关注他们的进度，让他们知道他们遗漏了某些晦涩（或不那么晦涩）的部分流程，帮助他们理解“评审就绪”的含义等。您还承诺评审他们的代码——或者至少帮助他们找到合适的评审者。
指定您自己作为您的联络人： 如果您是 nova 核心或经验丰富的 nova 开发者，您已经接受了文化灌输。您知道如何驾驭这个过程。您知道如何要求评审。您仍然不能 +1/+2 自己的代码。
核心或经验丰富的 nova 开发者招募单独的联络人： 由于您不需要指导方面，您在这种情况下联络人的作用实际上只是承诺进行评审。虽然不是必需的，但提前获得这种承诺可能很好。
以上内容并非详尽无遗；显然，规范所有者和 nova 核心之间的中间地带有很多。希望这应该相当明显联络人的角色在这种中间地带如何转变。如果需要进一步澄清，请编辑此文档。
- 功能联络人不必是 nova 核心。
联络人的角色不需要 +2 权限。功能联络人应被理解为“经验丰富的 nova 开发者能够胜任这项工作”。也就是说，虽然 nova 核心通过被指定为核心而隐式地符合这种描述，但作为联络人提出的非核心应该根据具体情况进行评估（由规范的评审者）作为规范评审过程的一部分，以确定他们是否符合资格。大多数情况下，“我们知道你是谁”。（请注意，在经验丰富的非核心为他人的功能担任联络人的情况下，他们仍然承诺进行评审，尽管评审最多只能达到 +1。）
- 如何找到功能联络人？
如果您尚未与某人达成协议作为您的联络人，请在您的规范草案中注明。您可以通过在 IRC (
#openstack-nova) 上与 nova 开发团队沟通、在 nova IRC 会议 中或通过 openstack-discuss 邮件列表来加速该过程。- 关于无规范蓝图？
我们将功能联络人的姓名放入蓝图描述中。它不如模板检查器自动强制执行，但就这样吧。
- 联络人职责与蓝图批准和优先级排序有何关系？
实际上没有。如果您注册成为蓝图 X 的联络人，nova 团队仍然可能决定蓝图 X 由于技术原因不可行；或者我们没有带宽来完成本周期的其他优先级。您只是在说，“如果这样做，我来负责。”
- 联络人职责与规范的 gerrit 评审有何关系？
联络人可以（并且应该，尽管目前不是硬性要求）评审和 +2/+1 他们作为联络人的规范（但不是所有者）。但是，我们仍然鼓励每个人评审和批准其他规范（否则什么也做不了）（另请参见下文）。（如果对规范补丁的赞成票也充当承诺评审相应代码的承诺，那将会很好，但联络人流程目前没有试图解决这个问题。）
- 我仍然被允许关心/评审/引导我没有自愿担任联络人的其他已批准的功能吗？
当然。重点是相反：如果您没有关注您注册的功能，人们会在您的照片上画胡子。或者如果您已经留了胡子，则画角。
