本指南适用于希望帮助审核代码的所有提交者和贡献者。感谢你的努力 - 良好的审核是开源项目中最重要也是最关键的部分之一。本文旨在协助社区开展代码审核工作,以达到下列目的:
{% toc %}
每次审核都需要检查以下六个方面。我们建议按照以下顺序进行检查,以避免在还没有就是否添加某项功能或需要改动达成共识之前或没有满足一些正式条件前,就花费时间进行详细的代码质量审核。
检查贡献是否有充分的描述以方便审核,不重要的更改和修复不需要很长的描述。如果实现方案完全是[按照之前在 Jira 或 dev 邮件列表上讨论结论]({{ site.base }}/zh/contributing/contribute-code.html#consensus)进行的话,只需要一个对讨论的简短的引用即可。 如果实现方案与之前达成一致的方案不同的话,关于实现的详细描述是需要的,以便 review 贡献时更深入地讨论。
任何改变功能或行为的 pull request 都需要描述这些改变的重点, 以便知道审核什么内容(并且不必钻研代码来了解更改的作用)。
需要更长描述的更改,理想情况下基于邮件列表或 JIRA 中的事先设计讨论,可以简单地链接到那里或从那里复制描述。
如果在不查看代码的情况下能回答以下问题2、3、4,则该贡献得到了很好的描述。
这个问题要直接在关联的 Jira issue 中回答。对于在达成一致前创建的 pull request 来说,需要[先在 Jira 中寻求一致的意见]({{ site.base }}/zh/contributing/contribute-code.html#consensus)。
对于[hotfix]
类型的的 pull request,可以在 pull request 中寻求意见一致。
一些更改需要特定的 committer 的注意和批准。例如,对性能非常敏感或对分布式协调和容错有关键影响的部件中的更改,这需要一个对相应组件非常熟悉的 committer 的审核。
根据经验,当 pull request 描述中对模板里问题 “Does this pull request potentially affect one of the following parts” 的回答为 “yes” 时,需要特别注意。
这个问题可以参考如下回答
如果 pull request 需要特别关注,则其中一个标记的 committers 或 contributors 应该给出最终批准。
在这一步中,我们会检查一个贡献的实现是否遵循了在 Jira 或邮件列表中商定的方案。 这个问题应该尽可能地从 pull request 描述(或链接的 Jira )中得到回答。
我们建议你在深入了解更改的各个部分进行评论之前先检查这一点。
这是对实际变更的详细代码审核,包括:
可以在 [Flink代码样式和质量指南]({{ site.baseurl }}/zh/contributing/code-style-and-quality.html) 中找到编码的规范和指南。
如果这个 pull request 引入了一个新功能,该功能应该被文档化。Flink 社区正在同时维护英文和中文文档。所以如果你想要更新或扩展文档,英文和中文文档都需要更新。如果你不熟悉中文,请创建一个用于中文文档翻译的 JIRA 并附上 chinese-translation
的组件名,并与当前 JIRA 关联起来。如果你熟悉中文,我们鼓励在一个 pull request 中同时更新两边的文档。
阅读[如何贡献文档]({{ site.baseurl }}/zh/contributing/contribute-documentation.html)了解更多。
Flink 社区正在使用名为 @flinkbot 的服务来帮助审核 pull request。
针对每个新的 pull request,机器人都会自动发表评论并跟踪审核进度:
### Review Progress * [ ] 1. The description looks good. * [ ] 2. There is consensus that the contribution should go into to Flink. * [ ] 3. [Does not need specific attention | Needs specific attention for X | Has attention for X by Y] * [ ] 4. The architectural approach is sound. * [ ] 5. Overall code quality is good. Please see the [Pull Request Review Guide](https://flink.apache.org/contributing/reviewing-prs.html) if you have questions about the review process.
审核人可以指示机器人(按顺序)勾选方框以指示审核的进度。
用于批准贡献的描述,请使用 @flinkbot approve description
@机器人。consensus
、architecture
、 quality
情况的操作与之类似。
要批准全部方面,请在 pull request 中添加一条带有 @flinkbot approve all
的新评论。
提醒他人关注的语法是 @flinkbot attention @username1 [@username2 ..]
。