添加或更改指南流程

本文档描述了在指南目录中合并非平凡变更集之前的流程。非平凡变更集是指不仅仅是拼写/语法错误或重新格式化更改的变更集。

指南最初的意图是作为一组草案文档。我们的目标是快速推进以发布草案指南，因此此流程反映了在达成共识的同时注重效率的偏好。

审查流程

对于琐碎的更改（如上文定义），在合并之前无需提出最低时间要求。它们必须至少获得除批准者之外的一个 +1 投票，且没有 -1 投票。一旦满足此条件，工作组核心成员即可合并更改。

对于添加新指南或对现有指南进行实质性更改的更改，达成共识是一个明确的目标。为此，有一个明确定义的流程，以确保提案获得 API 特别兴趣组、跨项目联络人和 OpenStack 社区的充分审查。

在审查流程的各个阶段（如下定义），共识意味着变更集在至少两个工作日内处于接近最终的形式。轻微的拼写/格式错误不会重置计数器。必须至少有四个 +1 投票，且没有 -1 投票，除非与 -1 投票相关的担忧已在 API WG 会议上讨论过。一旦讨论了此事，-1 投票的比例不应超过投票总数的 20%。

应鼓励在 Gerrit 上进行讨论作为主要响应方式。如果需要在 IRC 上（在会议或其他场合）进行讨论，则应将讨论内容总结回 Gerrit。

该流程是

1. API 特别兴趣组的成员应审查拟议的指南更改并达成共识。

2. 当组内达成共识时，应将指南标记为 *冻结*，并邀请跨项目联络人 (CPL) 审查该指南。有一个add-reviewers.py脚本来执行此操作。有关更多信息，请参见 跨项目联络人。

   只有一位核心审查员可以通过设置 Code-Review +2 来冻结提案。只有负责冻结提案的核心审查员才应 +2。其他所有核心审查员在审查时应以最多 +1 的投票进行投票。

3. CPL 有一周的时间来审查提案。如果没有审查，则假定为懒惰共识。如果 CPL 有 -1 审查，需要更新变更集，则不会重置 CPL 审查提案的一周时间。

4. 当 CPL 达成共识时，可以合并该提案。

   为了避免沟通不畅的机会，冻结变更集的核心工作组成员应负责合并它。如果该核心成员无法在足够长的时间内提供支持而导致延迟，则责任将落到其他核心成员之一身上。

   应向 openstack-dev 邮件列表发送一封电子邮件，其中包含指向所有最近合并的指南的链接。最终的指南应进行缓冲，以便每周最多发送一封公告电子邮件。

如果在此过程中任何时候难以达成共识或明显缺乏信息或输入，应从社区的其余部分寻求更多输入。有两种方法可以做到这一点（首选电子邮件）

1. openstack-dev 邮件列表。可以向 openstack-dev 邮件列表发送一封主题为“[all][api] 新 API 指南已准备好进行跨项目审查”的电子邮件。该电子邮件应包含指向需要更多输入的指南的链接。
2. 跨项目会议。应在跨项目会议中添加一个议程项目，指示需要讨论。应提供指向需要更多输入的指南的链接。当这样做时，API WG 的一名成员必须参加会议以突出显示议程项目。

合并的指南构成官方指南的草案。在可以发布官方版本的指南之前，必须发生以下情况

• 对整个文档进行 80%（投票总数）多数票，每位 OpenStack PTL（或代表）一票。
• TC 审查并批准。API WG 是 TC 委托的组，因此 TC 最终对工作组能够发布的内容拥有最终决定权。

提出新指南

在提出新指南时，应首先使用 指南模板 生成基本结构。复制template.rst文件到guidelines目录，文件名为反映您的新指南（例如guidelines/errors.rst），然后按照模板中的说明进行操作。完成后，应遵循 开发人员工作流程 和之前所述的审查流程，以使您的指南获得批准。