代码审查流程¶

所有提交到 Twisted 主干的代码都必须遵循此审查流程。

作者和审阅者都应该熟悉本页面的所有要求。

贡献者/PR 作者的简短说明

首先创建一个 GitHub 问题，描述问题或更改所需的原因。
遵循我们的编码规范并实施必要的更改
创建一个 GitHub 拉取请求，将更改合并到主干中
确保所有 PR 检查都为绿色，并且更改已准备好进行审查。
在 PR 上留下明确的评论，其中包含“请审查”文本。您可以使用“草稿 PR”，但一旦准备好，请留下明确的评论请求审查。这将触发审查流程，并向所需的团队发送通知。
等待审查，或尝试通过 IRC、邮件列表或 Gitter 找到审查
与审阅者进行对话，以获得更改的批准。
一旦 PR 中的更改获得批准，就可以合并 PR。

作者：开始之前¶

在大多数情况下，我们希望您立即开始编写代码！代码审查流程应该会发现您贡献中的任何严重问题，而持续集成系统应该会发现大多数棘手的跨平台问题。很容易过分关注第一次就做到完美，而最终没有写任何代码，因此您通常应该倾向于尝试一下，而不是等待有人告诉您是否可以这样做。也就是说，在您编写第一行代码之前，您应该了解一些事项。

确保您对需要完成的工作有一个明确的认识。首先写下您的想法；提交一个问题，然后再编写补丁。一个非常好的问题会精确地描述需要更改的内容以及更改的原因；它避免了对代码需要更改的具体方式给出精确的细节，因为补丁应该提供这些细节。一个非常糟糕的问题会说“这里有一个我写的补丁，请应用它”。如果您刚开始为 Twisted 贡献代码，最好找到一个现有的问题，而不是自己想出一个问题，这样您就可以在开始进行困难的更改之前了解如何完成整个流程。您需要对您的工作有一个很好的描述，以便在流程的其他部分中使用（NEWS 文件、提交消息），这也是考虑您正在尝试做的事情有助于的另一个原因。

**如果您因为注意到当前预发布版本中的回归而提交了一个错误，请确保将其标记为回归，将其添加到发布里程碑中，并在邮件列表中发布一些内容。**对于我们来说，在回归进入最终版本之前发现它们非常重要，因此在这种情况下，冗余的沟通更好！

问题应该描述得足够详细，以至于更改已经得到证明，并且新代码应该足够容易阅读，以至于不需要进一步的解释就能理解它，但有时差异本身可能比代码的旧状态或新状态更难阅读，因此像“foo 的实现从 bar.py 移动到 baz.py”这样的注释有时可以使审阅者的工作更容易。

尽量**不要**一次编写太多代码。一个好的更改需要在 1000 行差异以下，才能让审阅者在疲劳和遗漏某些东西之前处理它。您应该的目标是 200 行左右。这既是为了您的利益，也是为了审阅者的利益；我们不希望您在一个 10,000 行的庞大功能上花费数周时间，结果却因为我们根本不感兴趣而被拒绝。

作者：您的分支或补丁必须包含的内容¶

遵循编码规范的代码。

所有修改和新代码的 100% 单元测试覆盖率（即使它以前没有测试）

所有修改和新代码的 100% API 文档字符串覆盖率（即使它以前没有文档）

没有向后不兼容的更改。在向 API 添加“公共”名称时也要谨慎，因为它们必须在将来得到支持。如果它可以以下划线开头，并且不会公开暴露，那么它可能应该这样做。

适当的新增或修改的“最终用户”指南文档（以 docs/ 目录中的 rst 文件形式）

所有相关“newsfragments”目录中的一个文件，描述影响用户的更改。请参阅下面的 Newsfiles 部分。

作者：如何获得您的更改审查¶

Twisted Github 问题跟踪器中必须有一个问题描述了所需的结果。
请参阅下面的更多信息。
**注意：**对于安全问题，请参阅安全。
创建一个 GitHub 拉取请求
编写评论或 PR 描述，其中包含与审阅者相关的任何信息。
一旦 PR 准备好进行审查，请在该 PR 上留下单独的评论，其中包含文本“请审查”。这将触发审查流程，并将通知审查团队。

审阅者：如何审查更改¶

熟悉 Twisted 代码库、编码规范和这些审查要求。

不要成为更改的作者。审查自己的代码毫无意义，我们假设在将代码推送到公共 PR 之前，您已经完成了第一轮自我审查。

确保所有检查都为**绿色**！

注意任何不可靠/不稳定的测试都应该创建一个单独的问题。

审查更改，并写下关于分支的所有潜在改进的详细评论（请参阅下面的 [#Howtobeagoodreviewer]）。

使用 GitHub 审查 UI 批准或请求对 PR 进行更改。

如果作者没有提交权限，请为他们合并更改或添加“需要合并”标签。

作者：如何将更改合并到主干¶

如果您的审阅者对您的 PR 的更改感到满意，您可以合并它。

在 GitHub PR 中检查所有测试是否为绿色（或者失败的测试只是无关/虚假失败）

使用 GitHub 合并按钮合并请求，使用 GitHub 默认提交主题，并使用 Twisted 要求的标准提交格式。请参阅下面的详细信息。

或者，您可以使用命令行并将更改合并到 Twisted 主干的检出版本中（作为合并提交，使用“git merge –no-ff”）并提交它。

如果此修复对正在进行的预发布版本有影响，请在邮件列表中宣布它，以便发布经理知道。

更改对发布流程有影响，如果

已经发布了预发布版本，但没有最终版本
此问题是一个已知的回归，现在已关闭，因此应该发布另一个预发布版本
此问题在发布里程碑中，现在已关闭，因此应该发布另一个预发布版本
作为最终审查的一部分，审阅者注意到这正在修复一些可能被认为是回归的内容。一般来说，如果有任何疑问，请与邮件列表沟通。邮件列表的流量相当低，因此关于有趣进展的额外噪音比让重要的修复漏掉要好得多。如果您不确定某件事是否算作回归，请让发布经理知道，以便他们可以决定。
如果没有出现回归，您可以删除源分支。

谁可以审查 PR？¶

更改必须由除更改作者以外的开发人员进行审查。如果更改是成对进行的，则必须由第三方进行审查。如果更改构成几个独立工作的人员的工作，则必须由非作者进行审查。

审阅者不一定必须熟悉正在更改的 Twisted 的特定区域，但他们应该对自己发现更改中的问题的能力充满信心。

Twisted 提交者可以审查任何人的 PR；由其他提交者提交的 PR 或由非提交者贡献者提交的 PR。如果非提交者贡献者提交了一个可以接受合并的 PR，则提交者有责任提交和合并 PR。当提交者审查 PR 时，如果审查中存在任何问题，他们将负责。

非提交者贡献者可以审查提交者提交的 PR。当非提交者进行通过审查时，提交者可以接受它并完成他们的更改，但他们将负责审查的充分性。因此，如果非提交者进行的审查您认为可能不完整，请将其放回审查中并解释他们可能错过了什么 - 这种审查审查对于确保更多人学习如何进行良好的审查非常重要！

如何成为一名优秀的审阅者¶

首先，确保所有明显的事项都已考虑在内。检查上面的“您的分支或补丁必须包含的内容”列表，并确保每个要点都适用于该分支。

审阅者可能出于各种原因拒绝更改，其中许多原因难以量化。请使用您的最佳判断，不要害怕指出不符合本文档中列出的分支要求列表的问题。

以下是一些在审阅更改时需要考虑的额外事项

代码是否以直观的方式编写，以便将来可以轻松维护，可能是由作者以外的开发人员维护？
如果它引入了新功能，该功能是否普遍有用，并且已经考虑并考虑了其长期影响？* 它会让应用程序开发人员感到困惑吗？* 它是否鼓励使用它的应用程序代码具有良好的结构并易于测试？* 它是否类似于 Twisted 提供的任何现有功能，因此它可能作为其他代码片段的扩展或修改更有意义，而不是一个全新的功能单元？
它是否需要新的文档和示例？

完成审阅后，请务必说明下一步应该是什么：例如，如果作者是提交者，他们是否可以在进行一些小修改后提交？如果您的审阅反馈更实质性，他们是否应该重新提交以进行另一次审阅？

如果您正式“进行审阅”，请确保您进行完整的审阅并查找“所有”这些内容，以便作者在他们的票证处于审阅状态时获得尽可能多的反馈。如果您没有时间进行完整的审阅，并且您只注意到票证中的一两件事，只需发表评论以帮助未来的审阅者，并且不要删除审阅关键字，以便其他审阅者可以查看。例如，说，“我刚检查了新闻文件，发现没有”，或者，“我在这些方法中看到了一些尾随空格”。如果您从审阅队列中删除 PR，您可能会大大增加作者必须等待真正全面审阅的时间，这非常令人沮丧。