| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| <meta charset="utf-8"> |
| <meta http-equiv="X-UA-Compatible" content="IE=edge"> |
| <meta name="viewport" content="width=device-width, initial-scale=1"> |
| <!-- The above 3 meta tags *must* come first in the head; any other head content must come *after* these tags --> |
| <title>Apache Flink: 如何审核 Pull Request</title> |
| <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon"> |
| <link rel="icon" href="/favicon.ico" type="image/x-icon"> |
| |
| <!-- Bootstrap --> |
| <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.4.1/css/bootstrap.min.css"> |
| <link rel="stylesheet" href="/css/flink.css"> |
| <link rel="stylesheet" href="/css/syntax.css"> |
| |
| <!-- Blog RSS feed --> |
| <link href="/blog/feed.xml" rel="alternate" type="application/rss+xml" title="Apache Flink Blog: RSS feed" /> |
| |
| <!-- jQuery (necessary for Bootstrap's JavaScript plugins) --> |
| <!-- We need to load Jquery in the header for custom google analytics event tracking--> |
| <script src="/js/jquery.min.js"></script> |
| |
| <!-- HTML5 shim and Respond.js for IE8 support of HTML5 elements and media queries --> |
| <!-- WARNING: Respond.js doesn't work if you view the page via file:// --> |
| <!--[if lt IE 9]> |
| <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script> |
| <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script> |
| <![endif]--> |
| </head> |
| <body> |
| |
| |
| <!-- Main content. --> |
| <div class="container"> |
| <div class="row"> |
| |
| |
| <div id="sidebar" class="col-sm-3"> |
| |
| |
| <!-- Top navbar. --> |
| <nav class="navbar navbar-default"> |
| <!-- The logo. --> |
| <div class="navbar-header"> |
| <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#bs-example-navbar-collapse-1"> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| </button> |
| <div class="navbar-logo"> |
| <a href="/zh/"> |
| <img alt="Apache Flink" src="/img/flink-header-logo.svg" width="147px" height="73px"> |
| </a> |
| </div> |
| </div><!-- /.navbar-header --> |
| |
| <!-- The navigation links. --> |
| <div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1"> |
| <ul class="nav navbar-nav navbar-main"> |
| |
| <!-- First menu section explains visitors what Flink is --> |
| |
| <!-- What is Stream Processing? --> |
| <!-- |
| <li><a href="/zh/streamprocessing1.html">What is Stream Processing?</a></li> |
| --> |
| |
| <!-- What is Flink? --> |
| <li><a href="/zh/flink-architecture.html">Apache Flink 是什么?</a></li> |
| |
| |
| |
| <!-- What is Stateful Functions? --> |
| |
| <li><a href="/zh/stateful-functions.html">What is Stateful Functions?</a></li> |
| |
| <!-- Use cases --> |
| <li><a href="/zh/usecases.html">应用场景</a></li> |
| |
| <!-- Powered by --> |
| <li><a href="/zh/poweredby.html">Flink 用户</a></li> |
| |
| |
| |
| <!-- Second menu section aims to support Flink users --> |
| |
| <!-- Downloads --> |
| <li><a href="/zh/downloads.html">下载</a></li> |
| |
| <!-- Getting Started --> |
| <li class="dropdown"> |
| <a class="dropdown-toggle" data-toggle="dropdown" href="#">教程<span class="caret"></span></a> |
| <ul class="dropdown-menu"> |
| <li><a href="https://ci.apache.org/projects/flink/flink-docs-release-1.11/zh/getting-started/index.html" target="_blank">With Flink <small><span class="glyphicon glyphicon-new-window"></span></small></a></li> |
| <li><a href="https://ci.apache.org/projects/flink/flink-statefun-docs-release-2.1/getting-started/project-setup.html" target="_blank">With Flink Stateful Functions <small><span class="glyphicon glyphicon-new-window"></span></small></a></li> |
| <li><a href="/zh/training.html">Training Course</a></li> |
| </ul> |
| </li> |
| |
| <!-- Documentation --> |
| <li class="dropdown"> |
| <a class="dropdown-toggle" data-toggle="dropdown" href="#">文档<span class="caret"></span></a> |
| <ul class="dropdown-menu"> |
| <li><a href="https://ci.apache.org/projects/flink/flink-docs-release-1.11" target="_blank">Flink 1.11 (Latest stable release) <small><span class="glyphicon glyphicon-new-window"></span></small></a></li> |
| <li><a href="https://ci.apache.org/projects/flink/flink-docs-master" target="_blank">Flink Master (Latest Snapshot) <small><span class="glyphicon glyphicon-new-window"></span></small></a></li> |
| <li><a href="https://ci.apache.org/projects/flink/flink-statefun-docs-release-2.1" target="_blank">Flink Stateful Functions 2.1 (Latest stable release) <small><span class="glyphicon glyphicon-new-window"></span></small></a></li> |
| <li><a href="https://ci.apache.org/projects/flink/flink-statefun-docs-master" target="_blank">Flink Stateful Functions Master (Latest Snapshot) <small><span class="glyphicon glyphicon-new-window"></span></small></a></li> |
| </ul> |
| </li> |
| |
| <!-- getting help --> |
| <li><a href="/zh/gettinghelp.html">获取帮助</a></li> |
| |
| <!-- Blog --> |
| <li><a href="/blog/"><b>Flink 博客</b></a></li> |
| |
| |
| <!-- Flink-packages --> |
| <li> |
| <a href="https://flink-packages.org" target="_blank">flink-packages.org <small><span class="glyphicon glyphicon-new-window"></span></small></a> |
| </li> |
| |
| |
| <!-- Third menu section aim to support community and contributors --> |
| |
| <!-- Community --> |
| <li><a href="/zh/community.html">社区 & 项目信息</a></li> |
| |
| <!-- Roadmap --> |
| <li><a href="/zh/roadmap.html">开发计划</a></li> |
| |
| <!-- Contribute --> |
| <li><a href="/zh/contributing/how-to-contribute.html">如何参与贡献</a></li> |
| |
| <ul class="nav navbar-nav navbar-subnav"> |
| <li > |
| <a href="/zh/contributing/contribute-code.html">贡献代码</a> |
| </li> |
| <li class="active"> |
| <a href="/zh/contributing/reviewing-prs.html">审核 Pull Request</a> |
| </li> |
| <li > |
| <a href="/zh/contributing/code-style-and-quality-preamble.html">代码样式与质量指南</a> |
| </li> |
| <li > |
| <a href="/zh/contributing/contribute-documentation.html">贡献文档</a> |
| </li> |
| <li > |
| <a href="/zh/contributing/docs-style.html">Documentation Style Guide</a> |
| </li> |
| <li > |
| <a href="/zh/contributing/improve-website.html">贡献网站</a> |
| </li> |
| </ul> |
| |
| |
| <!-- GitHub --> |
| <li> |
| <a href="https://github.com/apache/flink" target="_blank">Flink on GitHub <small><span class="glyphicon glyphicon-new-window"></span></small></a> |
| </li> |
| |
| |
| |
| <!-- Language Switcher --> |
| <li> |
| |
| <a href="/contributing/reviewing-prs.html">English</a> |
| |
| </li> |
| |
| </ul> |
| |
| <ul class="nav navbar-nav navbar-bottom"> |
| <hr /> |
| |
| <!-- Twitter --> |
| <li><a href="https://twitter.com/apacheflink" target="_blank">@ApacheFlink <small><span class="glyphicon glyphicon-new-window"></span></small></a></li> |
| |
| <!-- Visualizer --> |
| <li class=" hidden-md hidden-sm"><a href="/visualizer/" target="_blank">Plan Visualizer <small><span class="glyphicon glyphicon-new-window"></span></small></a></li> |
| |
| <hr /> |
| |
| <li><a href="https://apache.org" target="_blank">Apache Software Foundation <small><span class="glyphicon glyphicon-new-window"></span></small></a></li> |
| |
| <li> |
| <style> |
| .smalllinks:link { |
| display: inline-block !important; background: none; padding-top: 0px; padding-bottom: 0px; padding-right: 0px; min-width: 75px; |
| } |
| </style> |
| |
| <a class="smalllinks" href="https://www.apache.org/licenses/" target="_blank">License</a> <small><span class="glyphicon glyphicon-new-window"></span></small> |
| |
| <a class="smalllinks" href="https://www.apache.org/security/" target="_blank">Security</a> <small><span class="glyphicon glyphicon-new-window"></span></small> |
| |
| <a class="smalllinks" href="https://www.apache.org/foundation/sponsorship.html" target="_blank">Donate</a> <small><span class="glyphicon glyphicon-new-window"></span></small> |
| |
| <a class="smalllinks" href="https://www.apache.org/foundation/thanks.html" target="_blank">Thanks</a> <small><span class="glyphicon glyphicon-new-window"></span></small> |
| </li> |
| |
| </ul> |
| </div><!-- /.navbar-collapse --> |
| </nav> |
| |
| </div> |
| <div class="col-sm-9"> |
| <div class="row-fluid"> |
| <div class="col-sm-12"> |
| <h1>如何审核 Pull Request</h1> |
| |
| <hr /> |
| |
| <p>本指南适用于希望帮助审核代码的所有提交者和贡献者。感谢你的努力 - 良好的审核是开源项目中最重要也是最关键的部分之一。本文旨在协助社区开展代码审核工作，以达到下列目的：</p> |
| |
| <ul> |
| <li>让贡献者拥有良好的贡献体验。</li> |
| <li>将审核过程结构化，以涵盖所有需要检查的重要方面。</li> |
| <li>保持 Flink 代码的高质量。</li> |
| <li>避免贡献者和审核者花费大量时间完善代码却最终被拒绝提交的情况。</li> |
| </ul> |
| |
| <hr /> |
| |
| <div class="page-toc"> |
| <ul id="markdown-toc"> |
| <li><a href="#section" id="markdown-toc-section">审核清单</a> <ul> |
| <li><a href="#section-1" id="markdown-toc-section-1">1.贡献的描述是否清晰？</a></li> |
| <li><a href="#flink" id="markdown-toc-flink">2.是否一致认为这一变更或者功能应该进入 Flink？</a></li> |
| <li><a href="#committer--committer-" id="markdown-toc-committer--committer-">3. 贡献是否需要一些特定的 committer 的关注，这些 committer 有时间投入吗？</a></li> |
| <li><a href="#section-2" id="markdown-toc-section-2">4. 实现方案是否遵循了商定的整体方案/架构？</a></li> |
| <li><a href="#flink-" id="markdown-toc-flink-">5.整体代码质量是否良好，是否符合我们希望在 Flink 中维护的标准？</a></li> |
| <li><a href="#section-3" id="markdown-toc-section-3">6. 英文和中文文档是否都更新了？</a></li> |
| </ul> |
| </li> |
| <li><a href="#flinkbot-" id="markdown-toc-flinkbot-">使用 @flinkbot 进行审核</a></li> |
| </ul> |
| |
| </div> |
| |
| <h2 id="section">审核清单</h2> |
| |
| <p>每次审核都需要检查以下六个方面。我们建议按照以下顺序进行检查，以避免在还没有就是否添加某项功能或需要改动达成共识之前或没有满足一些正式条件前，就花费时间进行详细的代码质量审核。</p> |
| |
| <h3 id="section-1">1.贡献的描述是否清晰？</h3> |
| |
| <p>检查贡献是否有充分的描述以方便审核，不重要的更改和修复不需要很长的描述。如果实现方案完全是<a href="/zh/contributing/contribute-code.html#consensus">按照之前在 Jira 或 dev 邮件列表上讨论结论</a>进行的话，只需要一个对讨论的简短的引用即可。 |
| 如果实现方案与之前达成一致的方案不同的话，关于实现的详细描述是需要的，以便 review 贡献时更深入地讨论。</p> |
| |
| <p>任何改变功能或行为的 pull request 都需要描述这些改变的重点, 以便知道审核什么内容(并且不必钻研代码来了解更改的作用)。</p> |
| |
| <p>需要更长描述的更改，理想情况下基于邮件列表或 JIRA 中的事先设计讨论，可以简单地链接到那里或从那里复制描述。</p> |
| |
| <p><strong>如果在不查看代码的情况下能回答以下问题2、3、4，则该贡献得到了很好的描述。</strong></p> |
| |
| <hr /> |
| |
| <h3 id="flink">2.是否一致认为这一变更或者功能应该进入 Flink？</h3> |
| |
| <p>这个问题要直接在关联的 Jira issue 中回答。对于在达成一致前创建的 pull request 来说，需要<a href="/zh/contributing/contribute-code.html#consensus">先在 Jira 中寻求一致的意见</a>。</p> |
| |
| <p>对于<code>[hotfix]</code>类型的的 pull request，可以在 pull request 中寻求意见一致。</p> |
| |
| <hr /> |
| |
| <h3 id="committer--committer-">3. 贡献是否需要一些特定的 committer 的关注，这些 committer 有时间投入吗？</h3> |
| |
| <p>一些更改需要特定的 committer 的注意和批准。例如，对性能非常敏感或对分布式协调和容错有关键影响的部件中的更改，这需要一个对相应组件非常熟悉的 committer 的审核。</p> |
| |
| <p>根据经验，当 pull request 描述中对模板里问题 “Does this pull request potentially affect one of the following parts” 的回答为 “yes” 时，需要特别注意。</p> |
| |
| <p>这个问题可以参考如下回答</p> |
| |
| <ul> |
| <li><em>Does not need specific attention</em></li> |
| <li><em>Needs specific attention for X (X 可以是例如 checkpointing、jobmanager 等)</em></li> |
| <li><em>Has specific attention for X by @commiterA, @contributorB</em></li> |
| </ul> |
| |
| <p><strong>如果 pull request 需要特别关注，则其中一个标记的 committers 或 contributors 应该给出最终批准。</strong></p> |
| |
| <hr /> |
| |
| <h3 id="section-2">4. 实现方案是否遵循了商定的整体方案/架构？</h3> |
| |
| <p>在这一步中，我们会检查一个贡献的实现是否遵循了在 Jira 或邮件列表中商定的方案。 |
| 这个问题应该尽可能地从 pull request 描述（或链接的 Jira ）中得到回答。</p> |
| |
| <p>我们建议你在深入了解更改的各个部分进行评论之前先检查这一点。</p> |
| |
| <hr /> |
| |
| <h3 id="flink-">5.整体代码质量是否良好，是否符合我们希望在 Flink 中维护的标准？</h3> |
| |
| <p>这是对实际变更的详细代码审核，包括：</p> |
| |
| <ul> |
| <li>变更是否按照 Jira issue 或 pull request 说明中的描述进行？</li> |
| <li>代码是否遵循正确的软件工程实践？代码是否正确、健壮、可维护、可测试？</li> |
| <li>在更改性能敏感部分时，是否对性能进行了优化？</li> |
| <li>测试是否覆盖了全部改动？</li> |
| <li>测试执行速度是否够快？（是否仅在必要时才使用重量级集成测试？）</li> |
| <li>代码格式是否遵循 Flink 的 checkstyle 模式？</li> |
| <li>代码是否避免引入额外的编译器警告？</li> |
| <li>如果依赖更新了，NOTICE 文件是否也更新了？</li> |
| </ul> |
| |
| <p>可以在 <a href="/zh/contributing/code-style-and-quality.html">Flink代码样式和质量指南</a> 中找到编码的规范和指南。</p> |
| |
| <hr /> |
| |
| <h3 id="section-3">6. 英文和中文文档是否都更新了？</h3> |
| |
| <p>如果这个 pull request 引入了一个新功能，该功能应该被文档化。Flink 社区正在同时维护英文和中文文档。所以如果你想要更新或扩展文档，英文和中文文档都需要更新。如果你不熟悉中文，请创建一个用于中文文档翻译的 JIRA 并附上 <code>chinese-translation</code> 的组件名，并与当前 JIRA 关联起来。如果你熟悉中文，我们鼓励在一个 pull request 中同时更新两边的文档。</p> |
| |
| <p>阅读<a href="/zh/contributing/contribute-documentation.html">如何贡献文档</a>了解更多。</p> |
| |
| <h2 id="flinkbot-">使用 @flinkbot 进行审核</h2> |
| |
| <p>Flink 社区正在使用名为 <a href="https://github.com/flinkbot">@flinkbot</a> 的服务来帮助审核 pull request。</p> |
| |
| <p>针对每个新的 pull request，机器人都会自动发表评论并跟踪审核进度：</p> |
| |
| <div class="highlight"><pre><code>### 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. |
| </code></pre></div> |
| |
| <p>审核人可以指示机器人（按顺序）勾选方框以指示审核的进度。</p> |
| |
| <p>用于批准贡献的描述，请使用 <code>@flinkbot approve description</code> @机器人。<code>consensus</code>、<code>architecture</code> 、 <code>quality</code> 情况的操作与之类似。</p> |
| |
| <p>要批准全部方面，请在 pull request 中添加一条带有 <code>@flinkbot approve all</code> 的新评论。</p> |
| |
| <p>提醒他人关注的语法是 <code>@flinkbot attention @username1 [@username2 ..]</code>。</p> |
| |
| |
| |
| </div> |
| </div> |
| |
| </div> |
| </div> |
| |
| <hr /> |
| |
| <div class="row"> |
| <div class="footer text-center col-sm-12"> |
| <p>Copyright © 2014-2019 <a href="http://apache.org">The Apache Software Foundation</a>. All Rights Reserved.</p> |
| <p>Apache Flink, Flink®, Apache®, the squirrel logo, and the Apache feather logo are either registered trademarks or trademarks of The Apache Software Foundation.</p> |
| <p><a href="/privacy-policy.html">Privacy Policy</a> · <a href="/blog/feed.xml">RSS feed</a></p> |
| </div> |
| </div> |
| </div><!-- /.container --> |
| |
| <!-- Include all compiled plugins (below), or include individual files as needed --> |
| <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/js/bootstrap.min.js"></script> |
| <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery.matchHeight/0.7.0/jquery.matchHeight-min.js"></script> |
| <script src="/js/codetabs.js"></script> |
| <script src="/js/stickysidebar.js"></script> |
| |
| <!-- Google Analytics --> |
| <script> |
| (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ |
| (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), |
| m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) |
| })(window,document,'script','//www.google-analytics.com/analytics.js','ga'); |
| |
| ga('create', 'UA-52545728-1', 'auto'); |
| ga('send', 'pageview'); |
| </script> |
| </body> |
| </html> |
