审查文档

OpenStack 文档的处理方式与代码相同，并遵循标准的代码审查流程。要查看哪些文档更改已准备好进行审查，请使用 文档项目仪表板 或包含文档的存储库的相应 Gerrit 审查列表。

文档项目仪表板仅列出由文档项目或其子团队管理的存储库的更改。仪表板根据文档的受众进行分组。

要查看当前的提议更改，请确保注册并登录到 review.openstack 代码审查。有关 OpenStack 中审查流程的更多详细信息，请参阅 代码审查。

评审指南

存储库和核心团队

文档团队是文档项目子团队管理的许多存储库的核心。可以从 文档团队结构 获取这些子团队的列表。

对于 security-doc 存储库，规则是每个补丁需要文档核心和安全核心的批准。

审查文档补丁

在开始审查补丁之前，请务必仔细阅读 审查指南 以及 代码审查指南。完成后，请按照以下步骤提交补丁审查。

  1. 如果您想审查由文档项目或其子团队管理的存储库的补丁，请转到 文档项目仪表板。

    要审查项目团队存储库的补丁，请使用相应项目的 Gerrit 更改列表。

  2. 选择一个补丁集。

  3. 单击上传的文件以并排查看更改。

  4. 如果您看到一些不一致之处或对补丁所有者有疑问，您还可以突出显示相关行或单词，然后按键盘上的 ‘c’ 键，这将启用对该行或单词的直接评论。写好评论草稿后，单击 保存 按钮。

  5. 在 Zuul 检查 部分，单击 publishdocs 门控链接（对于 openstack-manuals，它被称为 build-tox-manuals-publishdocs）并审查构建的手册，以查看更改在网页上的显示效果。对于新的补丁，OpenStack CI 系统检查出现在 Gerrit 页面上需要一些时间。如果需要，您还可以 在本地构建补丁。

  6. 单击 回复 以投票并输入有关您审查的任何评论，然后单击 发布。

注意

具有 WorkInProgress (WIP) 状态的补丁在审查和可能的批准之前需要额外的工作。因此，您可以跳过这样的补丁，并在准备好后进行审查。有关更多信息，请参阅 正在进行的工作。

参见

同行评审

注意

以下信息仅适用于由文档项目管理的存储库。

获得核心评审员身份

核心评审员能够对他们拥有核心状态的项目中的内容进行 +2 并合并。核心状态授予那些不仅完成了足够数量的审查，而且在这些审查中也表现出谨慎和智慧的人。

核心评审员的角色很复杂，拥有一个优秀的团队对于任何 OpenStack 项目的成功至关重要。文档团队旨在拥有一个合适的、由核心评审员组成的团队，每个核心评审员都保持活跃和参与。任命核心评审员的过程旨在确保统计方法和提名方法之间取得良好的平衡。为此，核心团队的变化相对较快，不活跃的核心团队成员会被移除，并且活跃的核心团队成员会定期添加。这也有助于现有的核心团队快速识别有价值的团队成员。

流程如下

  • 每个月（通常在 1 日），文档 PTL 从 Stackalytics 报告中提取 openstack-manuals 的顶级提交者和评审员。

  • 然后，PTL 会咨询现有的核心团队和 OpenStack 社区，提供要从核心列表中删除和添加的名称列表。这通过使用 openstack-discuss@lists.openstack.org 邮件列表作为主要通信渠道以公开方式完成。将被移除的核心成员将在做出更改之前收到个人联系。

  • 现有的核心团队成员可以随时提名新的核心成员，并向 openstack-discuss@lists.openstack.org 邮件列表发送理由。需要获得其他现有核心团队成员的三次 +1 投票才能获得批准。

核心评审员职责

成为核心评审员会带来责任：您现在是门户的守护者，核心团队有责任确保没有不利因素通过，同时又不阻碍贡献。

成为核心评审员的一般说明位于 核心评审员指南 中。本节适用于 openstack-manuals 核心评审员。

在大多数情况下，补丁可以获得至少一次 +1 投票和两次 +2 投票后合并。第二个 +2 投票通常也是合并补丁的投票（通常称为 +2A 投票）。文档中对此规则的例外情况很少，主要例外情况是补丁破坏了构建并且需要快速修复的特殊情况。在这种情况下，您仍然应该尽可能寻求其他核心团队成员的帮助，并与 PTL 取得联系，以便他们了解问题。

如果您是核心团队成员，但认为自己不了解补丁的主题，无法自信地合并它，请投票 +1 并说明原因。过于谨慎总比过于自信好。

尽量不要过快合并补丁，即使它严格符合投票数量要求。让补丁静置几天通常很有帮助，以确保足够的人看到了更改。将团队负责人或其他主题专家添加到您认为需要更多专业知识才能做出良好决策的补丁中也很有价值。

关于审查严格程度的说明：关于好的补丁是什么样子，很少有指导方针，但通常的方法是，如果它在技术上准确并且比现有内容更好，那么它应该被批准。主要关注点是

  • 一般的拼写和语法。

  • 技术准确性。尽可能在自己的虚拟机上测试命令，以确保其准确性。检查任何相关的错误和邮件列表讨论，看看您可能还需要考虑其他什么。

  • “它是否比我们已经拥有的更好”的测试。检查差异，或查看文档站点上的当前文档，并确定更改是否是改进。如果错误超过几个，请为作者提供内联更正。如果只有一两个小错误（或在作者明确要求编辑帮助的情况下），请考虑签出补丁并自行编辑它。

最后，请记住：要友善。要乐于助人。作为核心评审员，您的工作是帮助人们合并补丁，而不是阻止他们。