代码审查(review)指南

本文将介绍谁可以审查此项目的拉取请求(pull requests)，并介绍如何如何在代码审查的时候符合 DevStream 社区的标准和代码准则(code of conduct)。所有审查者(reviewer)必须阅读本文档并同意遵守项目审查准则。不遵守这些准则的审查者相应的的审查权限可能会被收回。

审阅者角色

审阅者角色不同于维护者(maintainer)角色。

审阅者可以赞同(approve)拉取请求，但是没有合并(merge)权限。维护者有赞同权限和拉取请求合入权限。

价值观

所有审查者都必须遵守代码准则并受其保护。审查者不应容忍不良行为，并且被鼓励及时报告任何违反代码准则的行为。我们提到的所有价值观均提炼自我们的代码准则。

下面是如何基于代码准则开展代码审查工作的具体例子：

包容性

你应该保持热情与包容，尽量确保作者的代码被成功合入。当某一个特定的拉取请求没法被合入的时候，不管怎么说我们希望他们能够有一个好的体验并且愿意再次提交贡献。因此为我们应该尽量解答他们的疑问，在他们被阻塞的时候提供相应的帮助。

可持续性

通过一些强制的边界定义来避免懈怠。以下是一些具体的例子，审查者被鼓励做到这些：

作者提交的一个拉取请求应该满足基线期望，比如编写一些测试代码。
如果没有精力继续参与审查工作，你可以退出一个拉取请求的审查工作，并指派给其他审查者。
如果作者的行为不符合代码准则，请关闭PR，并告知行为准则委员会或相关人员。你不用去说服他。

信任

审查工作需要让人信服，你的行为既在构建也在帮助社区呵护项目中的”信任”。以下是我们建立信任的一些方式示例：

透明 - 如果拉取请求不会合并，请清楚地说明原因并关闭它。如果拉取请求在一段时间内不会被审查，请告知作者，以便他们调整期望值并了解被阻塞的原因
诚信 - 在决定是否应合并变更时，将项目的最佳利益置于个人关系或公司隶属关系之前。
稳定 - 仅当更改不会对项目稳定性产生负面影响时，才会合并。合并不符合我们质量标准的拉取请求有时候可能很有诱惑，例如，当审查已经延期了一些时间，或者因为我们试图快速交付新功能，但回归可能会严重损害项目的”信任”。

流程

拉取请求可能会根据 OWNERS 文件自动分配。如果没有，任何审阅者都可以认领拉取请求的审查工作，并设置相应的标签。
项目用了 GitHub actions 来实现一些自动化，但目前没有使用额外的自动化/bot等将拉取请求自动分配给审查者。
审查者应等待自动化的 ci 检查通过后再进行审查工作。
文档/自动化相关的重要变更需要维护者进行审查。足够清晰的小调整不需要维护者的审查。如有疑问，请维护人员二次确认。
GitHub Actions 检查通过后才能合入拉取请求。唯一的例外是提交消息(commit message)检查失败，这可以通过 squash 操作和重新编辑来修复。
当拉取请求阻塞的时候，审查者应该主动联系贡献者帮助推进工作，或者向维护者报告状态。
通常，不建议审查者将更改直接提交到拉取请求。例外情况是：当原作者放弃拉取请求时；原作者是新的贡献者并且可能需要帮助。
维护者可以在审查完成后合并他们自己的拉取请求。
维护人员可以在必要的时候合并没有经过审查的拉取请求。

检查清单

以下是一组适用于所有拉取请求的常见问题：

这个拉取请求是否指向正确的分支？
提交消息是否提供了足够的更改描述？
提交消息是否遵循提交消息规范?
相关代码是否包含相应的测试？
更改是否有相应的文档，不仅是直接相关的文档，比如有新特性的时候是否提供了相关的概览等概念介绍文档或者相应的基于任务的渐进式教程？思考是否应该在 DevStream 的博客上宣布此变更。
这是否是一个不先前兼容的版本，从而需要发布一些通知或者发布一个新的版本？

阅读列表

我们鼓励审稿人阅读以下文章，这会对常见的审查工作有所帮助：