拉取请求审查指南

对 Kibana 做出的每一个更改都必须符合高标准，虽然拉取请求的质量最终由作者负责，但 Kibana 团队成员有责任在审查过程中进行验证。

坦率地说，不可能建立一个具体的清单来涵盖我们在审查拉取请求时可能遇到的所有情况，因此本文档试图列出一些明显的共同要求，同时也概述了我们在进行任何拉取请求审查时应该有的一般理念。

我们不期望也不打算让拉取请求审查采用本文档的形式，即最上面的指南总是先应用，最下面的指南总是最后应用。应该将整个文档视为一个整体，而不是一系列必须按顺序完成的待办事项。

虽然审查过程始终由 Elastic 工作人员完成，但这些指南适用于所有拉取请求，无论它们是由社区成员还是 Elastic 工作人员创建的。

目标受众编辑

本文档的目标受众是拉取请求审查员。对于 Kibana 维护者来说，拉取请求审查是我们对贡献过程唯一拥有完全控制权的部分。任何给定拉取请求的作者可能不了解我们对拉取请求的最新期望，并且他们可能根本没有阅读过我们的指南。作为审查员，我们有责任指导人们完成这个过程，但如果没有一套通用的书面原则，就很难始终如一地做到这一点。

拉取请求作者也可以从阅读本文档中受益，因为它将有助于在早期在作者和审查员之间建立一套共同的期望。

快速拒绝编辑

每个拉取请求都是不同的，在审查任何给定的拉取请求之前，审查员应该考虑处理拉取请求审查的最佳方式，以便如果最终拒绝更改，则应尽早在流程中完成。

例如，审查员可能希望尽早在产品级别审查包含新 UI 功能的拉取请求。另一方面，也许作者正在提交一个过去由于关键架构决策而被拒绝的新功能，在这种情况下，审查员可能应该在深入研究其他任何内容之前，先关注架构的健全性。

三大重点编辑

我们希望在所有拉取请求中遵循许多独立的要求和指南，但有三件事特别突出，比其他所有事情都重要。

产品级审查编辑

审查员不仅要评估代码本身，还要评估产品中面向用户的更改的质量。这通常意味着他们需要在本地检出分支并“试用”它。除了“我们希望产品中进行此更改吗”的详细信息之外，审查员还应该寻找错误并评估实现的功能的可访问性和实用性。应特别注意错误情况和边缘情况，以确保它们在产品中得到妥善处理。

一致性、风格、可读性编辑

拥有相对一致的代码库是我们构建可持续项目的重要组成部分。在任何时候都有数十名活跃的贡献者，我们依靠自动化来帮助确保一致性 - 我们通过 CI 强制执行一套全面的代码检查规则。我们还将推出 prettier，使其更加自动化。

对于无法轻松自动化的内容，我们维护了一个风格指南，作者应遵守该指南，审查员在审查拉取请求时也应牢记该指南。

除此之外，我们就进入了主观领域。像“这不太可读”这样的说法几乎没有帮助，因为它们无法量化，但这并不意味着审查员应该完全忽略由于编写方式而难以理解的代码。编写任何特定代码都没有绝对“最佳”的方法，因此追求这种方法不应该是我们的目标。相反，审查员和作者都必须接受，可能有很多不同的适当方法可以用代码完成同一件事，只要贡献使用的是其中一种方法，那么我们就很好。

另一方面，如果审查员指出某个特定的代码块难以理解，那么第一个查看代码的人就很难理解它。如果审查员强烈认为这是一个问题，他们应该向作者提出这个问题以供考虑，并可能提出替代方案。审查员必须务实，他们的目标应该是推动讨论向前发展，而不是简单地设置障碍。

如果有疑问，参考代码库中的“现有技术”，尤其是在贡献代码库的区域内和周围，通常是一个好主意。

也可能有些时候，一个人会受到某个特定贡献的启发，想要引入一种新的代码风格方式，而我们已经有不同的风格指南或“现有技术”。在拉取请求中提出这一点是可以的，但最终该讨论应该分支到一个单独的问题或拉取请求中，以更新相应的指南。如果此更改是由审查员提示的，则不应阻止原始拉取请求。如果更改是由作者提示的，则他们可以选择更新拉取请求以与我们现有的指南保持一致（首选），或者他们可以选择完全阻止拉取请求，直到该单独的风格指南讨论结束。

吹毛求疵编辑

吹毛求疵是指审查员在拉取请求中找出微不足道且不重要的细节，并要求作者更改它们。这是一个完全主观的类别，不可能普遍定义，并且对吹毛求疵制定一个能让每个人都满意的全面政策也同样不切实际。

审查员应该能够自在地就拉取请求给出任何反馈，无论它多么微不足道。作者应该同样能够自在地忽略他们认为微不足道且无关紧要的反馈。

通常，审阅者对于他们将要给出的反馈是否吹毛求疵有自己的看法。虽然不是必需的，但将反馈标识为吹毛求疵非常有帮助，例如“nit：在此处添加换行符会有所帮助”。这有助于作者理解您的意图。

处理分歧编辑

审阅者和作者之间发生意见冲突很常见，而且有时很难调和这些意见。理想情况下，人们可以本着这些准则的精神共同努力达成共识，但如果这不起作用，最好让第三个人参与讨论。我们的拉取请求通常有两名审阅者，因此合适的第三个人可能已经很明显了。否则，请联系最合适的职能领域，或者在领域不明确的情况下联系技术负责人。

不恰当的审阅反馈编辑

一段反馈是否适合拉取请求通常取决于最初给出反馈的动机。

主要基于“我会如何编写这段代码？”的心态来*要求*作者进行更改是不合适的。审阅者没有编写代码，他们在审阅过程中的关键目的不是将贡献修改成他们自己会写成的形式。如果审阅者想提供这种类型的反馈，他们应该像在吹毛求疵部分提到的那样将其限定为“nit”，以明确表示作者可以选择接受或拒绝。

诸如“这太糟糕了”之类的煽动性反馈根本就不是反馈。它既刻薄又无益，而且永远不合适。

清单编辑

为所有可能的拉取请求中应该发生的所有事情建立一份全面的清单是不切实际的，但这并不意味着我们缺乏一套可以列举的具体最低要求。以下项目应针对任何拉取请求进行仔细检查