拉取请求

本文档作为您审查拉取请求的指南。

在审查 PR 时，请运用您的最佳判断，最重要的是，请记住在回复用户时要 **友善、友好和鼓励**。许多用户是开源和/或类型化代码检查的新手。我们必须为他们提供积极向上、鼓舞人心的体验。

提示

如果您对 PR 审查的任何部分有任何疑问，请随时联系具有更多上下文信息的维护者寻求帮助！

治理

根据 贡献者层级 > 指标 中的标准

• 简单：由审阅者自行决定，任何提交者或维护者都可以通过一次批准合并。这包括文档增强、错误修复和功能添加。
• 不简单：需要两次提交者批准或一次维护者批准才能合并。这包括多包内部重构和非破坏性公共 API 更改。
• “不寻常”类别：需要两次维护者批准。这包括对跨项目和公共 API 产生影响的重大重构。

PR 审查流程

注意

我们在 .github/replies.yml 中包含了一组对 PR 的常见回复，旨在与 Refined Saved Replies 扩展一起使用。不要将这些视为必须使用的确切回复：它们只是复制粘贴的起点。请根据您的个人语气和非简单 PR 的线程调整您的特定回复。

打开的拉取请求理想情况下会在两种状态之间切换

• 准备审查：要么是新创建的，要么是在 重新请求审查 之后
• 等待作者操作：要么是 草稿，要么是带有 awaiting response 标签

在发布审查时，将 awaiting response 标签添加到 PR。如果作者重新请求审查，该标签将自动删除。

友善

最重要的是，语气要鼓励和友好。

• 将反馈表达为改进的机会，而不是责备。
• 指出你看到的任何积极方面 - 特别是在较大的拉取请求中。
• 经常使用快乐的表情符号。
• 如果你有精力，可以发布一个有趣（但不过分）的 GIF 与你的评论一起。
  • 我们经常使用 GIFs for Github 扩展：可作为 GIFs for GitHub (Chrome) 和 GIFs for GitHub (Firefox) 获取。

拉取请求是许多社区成员与我们有意义地互动（或者，通常是与任何开源维护者互动）的第一次。我们必须提供积极、鼓舞人心的体验。❤️

审查 PR

在审查拉取请求之前，请尝试回顾一下支持问题，以便（重新）熟悉它。你可能会发现以下方法很有用

• 尝试简化提供的缩减 ("代码高尔夫")
• 回顾同一代码区域/lint 规则周围的先前问题和 PR

如果没有支持问题

• 如果 PR 是一个简单的文档或工具修复，不会影响用户，可以按原样审查它
• 否则，添加 please fill out the template 标签，并发布类似于 Needs Issue 模板的评论

完成你的审查后，如果构建通过，并且你感觉可以合并它，请继续进行压缩合并。否则，添加 1 approval 标签。

常见注意事项

• 样式：你可以轻松地阅读代码，对必要的棘手区域有注释，而其他地方没有不必要的注释。
  • 尽量不要吹毛求疵无关紧要的事情。
  • 如果某些内容在仓库中是标准的，但没有强制执行，请考虑将其作为非阻塞评论提及，并提交问题以强制执行它。
• 彻底性：它是否处理了相关的边缘情况？通常
  • 泛型和类型参数（参见：getConstrainedTypeAtLocation）。
  • 括号和空格（参见：getWrappingFixer）。
  • 联合和交集（参见：unionTypeParts 和 intersectionTypeParts）。
• 单元测试
  • 所有代码行都已覆盖，请参见 Codecov / yarn jest path/to/impacted/file --coverage 报告。
  • 如果合理，测试用例应包含“正向”和“负向”（“有效”和“无效”）两种情况。
  • 如果存在修复和建议，请勿删除 // 或 /* 注释。
  • invalid lint 规则错误包含行号和列号信息。
  • 即使在 TypeScript 中会导致类型错误，有效的语法边缘情况也不会导致规则崩溃。

单个评论

每个评论应针对一个赞赏点、建议的更改或非行动性说明。可以使用多个辅助评论来表示“（也在这里）”说明，但不要用请求淹没审阅者。

提示

如果您要发布多种类型的评论，请考虑在它们前面加上类别指示符，例如 [Docs]、[Praise]、[Testing] 等。这有助于避免审阅感觉像是一大堆繁重的请求。

在每个评论中明确说明您要查找的内容或要表达的内容。宁可提供过多的信息，也不要提供不足的信息。

对于不清楚的错误，尝试使用疑问语气。鼓励作者思考您的建议：“我认为（xyz），但不确定 - 您怎么看？”。

初步或重复审阅

有时您可能想发布初步审阅，或者后来意识到在之前的审阅中遗漏了一些内容。这两种情况都是合理的。

对于初步审阅，请明确说明您正在审阅的范围：“现在正在审阅架构，架构确定后会更详细地查看”。

对于重复审阅，请明确说明是您之前遗漏了一些内容，还是有新的信息。如果遗漏的信息只是因为请求的更改才变得清晰，不要道歉 - 这是审阅过程的一部分！

其他状态

外部阻碍

如果 PR 被某些东西阻碍，例如外部 API 或问题中的讨论，请添加相应的 blocked by * 标签。在评论中解释原因，并链接到至少一个跟踪阻碍者的问题。

带外问题

作者有时会以评论的形式在 PR 上单独提出问题，有时还会包含 @ 标签。如果你回答了这些问题，请将 awaiting response 标签放回。如果你漏掉了其中的一些问题，也不用担心；我们更倾向于通过正式的重新请求审查来确保 awaiting response 标签被移除。

修剪旧 PR

我们经常喜欢 搜索 awaiting response 状态的开放 PR，以找到可能被遗忘的 PR。对于等待时间超过 1 个月的 PR，我们的流程如下：

1. 使用类似于 Checking In 模板的消息 ping 作者
2. 在 PR 上添加 stale 标签
3. 等待 2 周
4. 如果他们仍然没有回复，请使用类似于 Pruning Stale PR 模板的消息关闭 PR

搜索 PR

其他一些用于 PR 的查询包括：

• 你评论过的所有 PR
• 所有非草稿、非 awaiting response 状态的 PR
• 所有非草稿、非 awaiting response 状态的 PR，且未被阻塞或已批准

如果你有时间，请考虑偶尔查看一下旧的 PR，以确保没有遗留数周未回答的问题。