指导审查流程¶

API 特别兴趣组希望通过定义一个流程和场所来进行现场面对面的审查，从而增加 OpenStack 项目团队可用的工具。从宏观层面上讲，这些审查的重点是“我的项目是否符合指南？” 并且计划由 API 特别兴趣组在 PTG 会议上主持。

从更具体的层面来看，API 特别兴趣组预计针对 API 的特定领域或问题进行的审查将获得最佳效果（例如，“使用 PUT 请求更新这些资源是否合适？”、“我们使用 GET 请求来启动服务器操作，是否有更好的替代方案？”）。

理想的审查候选对象¶

在 PTG 会议上审查一个项目的整个 API 可能会很困难，甚至不可能。因此，以下是一些选择讨论主题的建议

您的 API 的某个部分是否在您的团队中引起了一些分歧？如果是这样，那将是在 PTG 上讨论的一个绝佳主题。

您对当前 API 的某些工作方式不满意吗？我们可以集思广益，探讨如何使其更一致和易于使用。

您正在创建一个新的 API 吗？如果您正在启动一个新项目，或者为您的项目创建一个新的主要版本，我们可以讨论最有效的方法。

在向 API 工作组请求对您的项目进行现场审查之前，您应该准备以下事项

选择您要关注的 API 的一个领域（例如，特定的资源类型、一个棘手交互或需要澄清的端点）。
准备一份描述该 API 的文档，这可以是自由形式的，也可以是更正式的，例如 OpenAPI 规范。这不需要是一份详尽的文档，但应该有助于推动审查对话，并为审查者提供一个理解相关 API 流程的参考。

然后，只需带着您的材料参加 API 特别兴趣组的现场会议即可。提前发送电子邮件将有助于确保该组为您的审查做好准备，但并非绝对必要。

这取决于您对该组的请求性质。您应该期望澄清您的 API 遵循 API-SIG 指南的程度。但是，审查的深度将完全取决于对审查组提出的请求的大小。

项目团队在审查过程之前所做的准备将对预期的结果产生最大的影响。那些对审查组的请求更具体和集中的团队，最有可能从这个过程中获得最大的收益。

在考虑向 API-SIG 寻求审查时，我们鼓励项目识别其 API 中可能需要澄清或对团队造成问题的领域。审查过 API 指南并对特定感兴趣领域有疑问的项目团队会发现他们的审查比涵盖 API 大部分内容的开放式问题更有效。

审查完成后，API 特别兴趣组将归档审查的一般细节（例如，“团队 <X> 请求审查 API 功能 <Y> 和 <Z>。达成共识，行动 <A>、<B> 和 <C> 是最佳前进方向”）以及在此过程中生成的所有工件。此归档将存在于与指南相同的存储库中，并在审查的单独标题下。

TODO