评审指南

本节提供指导，以提高文档评审过程的质量和速度。

评审类别

以下是您作为评审员将要评审的类别列表。

客观

主观

  • 提交消息

    • 语法

    • 拼写

    • 风格、措辞和用词

  • 补丁

    • 语法

    • 风格、措辞和用词

    • 技术准确性

    • 其他建议

范围

尽量将评审限制在缺陷内容、提交消息内容以及补丁所做的更改范围内。换句话说，如果补丁解决了陈述的问题，但补丁可能会带来其他改进，请批准补丁并提交后续缺陷，而不是用关于改进的评论来 -1 补丁。这就是为什么编写清晰定义补丁范围的提交消息是一个好主意。

在补丁的客观和主观目标范围内，如果附加评论会导致 -1，则这些评论是合适的。请记住考虑更改是否与范围相关。

一致性

  • 如果补丁中出现某个问题，请标记所有实例。

    • 如果作者上传了更正您的客观问题的补丁，并且您发现另一个您未标记的实例，请评论它并以 -1 分数进行评分。最好上传补丁来修复它。

    • 如果作者上传了更正您的主观问题的补丁，并且您发现另一个您未标记的实例，请评论它并以 0 分数进行评分。

    • 如果作者上传了更正您的客观和/或主观问题的补丁，并且您发现另一个客观问题，请评论它并以 -1 分数进行评分。最好上传补丁来修复它。

    • 如果作者上传了更正您的客观和/或主观问题的补丁，并且您发现另一个主观问题，请评论它并以 0 分数进行评分。

  • 如果出现的问题可能会影响一本书的其他部分，请提供适当的评论，以 -1 分数对补丁进行评分，并考虑在邮件列表或会议上提及您的问题。

    示例：新的服务在配置文件中使用“key = value”，而所有其他服务在其配置文件中使用“key=value”。两种方法都可以工作，但本书应保持一致性。

  • 如果补丁已经收到 -1，不要灰心，请检查它并添加其他评论。这样，在一个评审下将会有更少的补丁集和评论。

标记其他评审员

在某些情况下，您应该标记一个或多个对您的补丁内容感兴趣或具有经验的人员进行评审。

问：作者应该等待这些人员的评审多长时间？

答：对于积压超过 400 个补丁的极其繁忙的项目，至少等待两周。如果您难以获得特定项目的评审员，请使用 跨项目文档联络员页面联系项目的文档联络员以获取评审员。文档 PTL 也可以协助获得评审员的关注。

等待游戏

在第一次评审中，如果得分是 -1 或 0，作者应更新补丁。作者无需等待很长时间。但是，请预计留出一些时间供评审员检查补丁，同时也要考虑到一些评审员位于不同的时区。

核心评审员通常会在几天内评审补丁。如果没有评审，请随时在 #openstack-doc IRC 频道上询问。

评审评分和批准

  • 贡献者可用的分数：-1、0、+1

  • 核心评审员可用的分数：-2、-1、0、+1、+2

  • 批准

如果另一个核心评审员给出 +2 分数，核心评审员可以对补丁进行 +2 分数评分并批准它。如果更改包含重要或关键信息，核心评审员不应立即批准它，而应留出几天时间供更广泛的社区成员表达他们的意见，并建议发布到文档邮件列表。

注意

如果您发现另一个核心评审员已经对补丁进行了 +2 分数评分的问题，请考虑评论该问题并以 0 分数对补丁进行评分，而不是以 -1 分数对其进行评分。

在评审期间设置 WorkInProgress (WIP)

WIP 标签告诉潜在的评审员预计在评审之前补丁会有额外的更新。更改的所有者和任何核心评审员都可以设置 WIP 状态

  • 更改所有者和核心评审员可以在他们自己的评审中设置此标签，以标记仍在进行其他更改，并避免在发生这种情况时进行不必要的评审。

这可以为其他评审员带来很大的便利。它允许核心评审员礼貌地发送消息，表明更改需要更多的工作，同时将其从准备好的更改列表中删除，直到发生这种情况。

要添加 WIP 标签

  1. 选择一个补丁集。

  2. 单击 回复… 按钮。

  3. 从 工作流选项中选择 -1 (正在进行中)。

  4. 可选：输入评论。

  5. 单击 发布。

这将设置一个 -1 并告知所有人补丁正在进行中。

放弃补丁

核心评审员可以放弃收到 -2 评审或至少四周没有活动的补丁，以使补丁评审队列保持新鲜。补丁的所有者也可以放弃它。所有者和核心评审员可以再次恢复它。

OpenStack Proposal Bot 的补丁

设置了一些定期运行的提案作业

  • 导入 来自 Zanata 的 翻译：从翻译基础设施导入翻译文件。每天运行一次 (06:00 UTC)，针对每个存储库。

  • 从 openstack-manuals 更新：从 openstack-manuals 导入词汇表文件。当 openstack-manuals 合并时会触发此作业，如果发生更改，则会提出更改。

  • 从 全局 需求 更新：从全局需求存储库导入 requirements.txt 和 test-requirements.txt。

对于所有类型的补丁，任何核心都可以批准补丁，如果所有测试都通过。如果测试未通过，请对补丁投票 -1，修复问题并等待下一次提案运行。提案作业将在下一次运行中更新补丁。如果您无法修复问题，请在邮件列表中寻求帮助

与发布周期对齐的文档的考虑因素

从里程碑版本开始，将重点转移到客观问题上，特别是对于新服务和具有重大更改的现有服务。只有具有重大主观问题的补丁才应收到 -1 分数。否则，评论主观问题并以 0 分数进行评分。从发布候选版本开始，几乎完全关注内容问题。仅当补丁应因客观问题而收到 -1 分数时，才评论主观问题。