码住！Flink Contributor 速成指南

简介：不管初衷是什么，Flink 都非常欢迎大家一起建设和完善社区。在开始具体的贡献步骤之前，我们先简要介绍一下参与贡献的几种途径，以及 Clarify 关于开源贡献的一些固有印象。

为什么要参与开源社区

作为 Apache Flink PMC member 的云邪根据自身经历总结了参与开源社区发展的三个主要原因。

image

1. 开源精神

「自由」可谓是开源精神的核心，自由意味着世界范围内无拘无束的交流分享与思维的碰撞。云邪自述“拿我个人来说，我在大学阶段正好经历了 Hadoop、Spark 大火的阶段，那时候就特别憧憬做开源，特别崇拜能熟读源码的大神，特别希望自己有一天也能够写很多开源代码，让自己写的代码被上万的用户使用。所以对于我来说，参与开源就像是一个爱好一样，愿意为之付出时间和努力。我也很幸运地在毕业后就接触上了开源社区。”

2. 技术成长

参与开源是提升个人代码质量的好方法。开源社区对于代码和设计要求非常高，不像一些内部项目相对随意。对于设计，Flink 社区有一套专门的 FLIP 机制，任何重大的贡献都会经过公开和细致的讨论。对于代码，Flink CTO 亲自写了 26 页的 Code style 指南，此外每次提交 PR 后也会收到 Committers 的 Review 建议，所以持续地在开源社区里贡献代码，对于个人的系统思维能力和代码能力都有很大提升。

3. 职业规划

如果你在准备跳槽或是公司内部晋升，除了现有的 Title 外，参与开源社区的经历绝对是一个加分项，因为开源产品本身就带有网红的标签，而参与其中则有助于提高自身的影响力 & 结识同行业的大牛们。开源贡献除了能直接地反映你的代码能力外，成为 Committer 甚至 PMC member 更能证明你的热情 & 毅力 & 沟通协作方面的 Soft skills（因为这需要你持续完成高质量的贡献，与社区其它成员共同协作，在有意见分歧的时候保持开放友好的态度 etc.）。

如何成为 Contributor

1. 贡献途径

不管初衷是什么，Flink 都非常欢迎大家一起建设和完善社区。在开始具体的贡献步骤之前，我们先简要介绍一下参与贡献的几种途径, 以及 Clarify 关于开源贡献的一些固有印象。

image

说起开源贡献可能大家的直观反应就是贡献代码。不过在 Flink 社区中有非常多的参与贡献的方式，包括文档、翻译、答疑、测试、以及代码等，并且社区将文档贡献放在第一位，代码贡献放在最后。因为 Apache 社区对于代码贡献的态度是 Community Over Code，Flink CTO 更是亲自发推说明代码贡献的“不重要性”。

image

为什么呢？因为开源项目的良性发展并不是简单地依靠狂怼代码，没有社区的开源项目，其源码会一直停留在「孤芳自赏」阶段。“我有一个想法，这是我的代码”可能是最糟糕的贡献方式，因为在没有任何文档的情况下 Committers 不得不通过代码去尝试理解贡献者的意图，这种反向推导往往会耗费 Committers 和贡献者本人额外的时间精力，导致非常高的沟通成本和更久的代码合并周期。另一方面，缺少严格的代码审查机制和规范的 Pull Requst 流程会导致开源代码的质量大幅降低，这就是为何小到发现 typo、简单的 bugfix 都需要有一套完整的机制，而大到一个模块的重构、feature 的新增更需要提供详细的设计文档、发起投票。这部分工作所占的比重非常高，所以真正到写代码的阶段是自然而然水到渠成的。而完善详尽的文档、及时准确的答疑、百花齐放的技术博客才能打造优质的社区生态，吸引更多的用户参与使用，进而反哺社区。拿最近成为 Committer 的 Konstantin 和 Seth 来说，他们提名的主要贡献就是文档，这也可以看出 Flink PMC 委员会对于文档贡献的认可和重视，特别是贡献中文文档（翻译）的门槛相对较低，只要有一定英语基础 & 文字表达能力即可，属于最适合初学者开始开源贡献的起步选择。Flink 社区目前正在招募翻译者，下面也会详细介绍翻译的具体流程。

2. 准备工作

• 订阅邮件列表 Flink 社区讨论主要通过邮件完成，所以参与贡献的第一步是加入到邮件列表获取最新的讨论信息。主要的邮件列表有用户邮件列表（user@flink.apache.org & user-zh@flink.apache.org）和开发者邮件列表（dev@flink.apache.org）。关于邮件列表的更多信息可以参考 https://flink.apache.org/community.html#mailing-lists 。发送邮件到相应的邮件列表并回复确认信息即可订阅。

E.g. 想订阅开发者邮件列表就发送无内容的邮件到 dev-subscribe@flink.apache.org，社区会回复一封邮件询问你是否确认加入，再回复一下确认就可以了。

Flink 社区每天来往的邮件非常多，有效整理归档可以帮忙自己快速定位相关 topic，云邪在这里分享了他的 Gmail 收件规则 https://gist.github.com/wuchong/ad6a3bd241aca0e04eef93ae71fba73b，可作为参考。

image

• 关注 JIRA 模块 Flink 社区通过 JIRA 管理所有 Issue，所以在开始贡献前我们需要有一个 JIRA 账号。虽然 JIRA 不支持关注某个特定的模块，但我们可以使用 JIRA Filters 来跟踪自己感兴趣的模块。 操作步骤如下

1. 切换到 JIRA Issues 页，将搜索框从 Basic 切换到 Advanced 模式。

2. 加入自己感兴趣的 Filter，比如以中文翻译为例， component = chinese-translation 就会筛选出所有翻译相关的 Issue，resolution = Unresolved AND assignee IN (EMPTY) 会在此基础上删选出 available 并且还没有指派给其他人的翻译任务。完整的过滤条件：project = FLINK AND component = chinese-translation AND resolution = Unresolved AND assignee IN (EMPTY) ORDER BY updatedDate DESC ，然后点击保存即可。此外可以按照自己感兴趣的模块创建多个 Filters 方便后续使用。

• 目前 Flink 社区只有 Committer 才有权限将 Issue 指派给自己，所以如果是 Contributor 想解决它的话可以在 Issue 下方留言申请指派。一般情况下如果是简单的 typo 或 bugfix 时 Committer 会直接指派，但如果涉及到比较复杂的改动或是新的 feature 实现，在申请时就需要阐述清楚代码层面的实现方案，与 Committer 达成一致后才会指派。另外可以点击 Issue 页面上的 Watchers 添加关注，后面这个 Issue 的任何更新都会发送到注册 JIRA 时使用的邮箱。

image

• Fork Flink 仓库 & 下载 Flink 源码

首先你需要有一个 GitHub 账号，然后打开 Flink 的 GitHub 主页 https://github.com/apache/flink 点击 fork 按钮，这样就在自己的私人仓库下生成了一份镜像。

然后在本地 clone Flink 仓库，用于同步 master 代码> git clone https://github.com/apache/flink.git ${your-local-dir}

接着添加自己 fork 的仓库用于提交开发分支> > git remote add {your-github-id}/flink.git> > E.g. 云邪的配置 > git remote add my https://github.com/wuchong/flink.git

开始第一个 Pull Request 之旅

对于参与社区的起步者，翻译模块通常是 “ROI” 最高的选择。因为它不仅易上手而且覆盖了标准贡献流程，分分钟让你变身 Apache Flink Contributor。下面我们将通过一个中文翻译例子来展示完整的 Pull Request（以下简称 PR） 流程。不过在起飞前，我们需要先了解翻译规范，这里简要总结三点：

• 使用纯文本工具进行翻译

• 汉字与英文、数字之间需要有空格

• 中文文档链接需要在相应英文文档的 baseUrl 后添加 zh 适配

在上述准备工作完成后，我们就进入激动人心的实战阶段了。

Step1：申请成为某个 JIRA Issue 的 Assignee。由于这里是演示任务，所以我们打开事先准备好的翻译任务 FLINK-17939 Translate "Python Table API Installation" page into Chinese，将它 assign 给自己（云邪）。

image

Step2：开始工作 & 检查待提交的内容。注意所有文档都以 .md 为后缀，中文文档名会有 zh 标识符，初始状态下中文文档里的内容都是英文。我们切换到本地仓库切换到 docs 目录下找到要翻译的文档，就可以遵循翻译规范开始工作了。

image

翻译工作完成后，最好在本地进行渲染查看效果后再进行提交，方法如下：

切换到 docs 下的 docker 目录启动 docker 环境

cd ${your-local-dir}/flink/docs/docker ./run.sh

紧接着编译本地文档，一般来说需要 1 ~ 2 min

./build docs.sh -p

然后打开 localhost:4000 切换到中文版就可以检查渲染后的文档，比如排版格式及页面里的超链接能否正常打开等等，确认无误后就可以提交了。注意：要为指向其他文档的超链接做中文适配。

image

Step3：提交阶段准备。最佳实践是创建一个用于提交的分支，将改动提交到这个分支上。比如这里创建一个叫 installation-translate 的分支并切换过去。

git checkout -b installation-translate

Flink 社区对 Commit Message 的格式有一定要求，一般是 [{affected-component}] ${jira-issue-title}。

以 Demo 为例，就是 [FLINK-17939][docs-zh] Translate "Python Table API Installation" page into Chinese

在本地提交后就可以通过下面的命令把改动推送到自己 fork 的远程私有仓库。

git push my installation-translate

Step4：准备 PR。在将变更推送到自己 fork 的远程仓库后，Github 会自动创建一个新的 PR 并返回 PR 页面链接 https://github.com/apache/flink/pull/12343，在此基础上需要填写如下信息，从而方便 reviewer 快速了解待 review 的 PR，提高合并效率。

• What is the purpose of the change（PR 目的）

• 一般来说可以使用 JIRA Issue description 来描述

• Brief change log（PR 涉及到的 Commits 做了哪些改动） 这个按需填写即可。比如翻译任务就可以写 translateflink/docs/dve/table/python/installation.zh.md。如果是较复杂的改动，涉及到多个提交的话，最好按提交顺序说明简要总结每个提交的内容并附上 Commit log 链接。

后面三个是选择题，按需勾选即可：

• Verifying this change（确认改动了哪些内容）

• Does this pull request potentially affect one of the following parts（确认改动的影响范围）

• Documentation（改动是否需要新文档）

image

Step5：等待 Committer review。此时刷新 JIRA 页通常可以看到 Issue Links 上的 PR 更新。一般来说将 JIRA issue 指派给我们的 Committer 都会定期去 check 是否有他关注模块的 PR，偶尔会遇到 Committer 很忙的情况时也可以在 PR 里 @ 某个 Committer 来帮忙 review 自己的提交。通常 Committer 都会给出一些意见，提交者做出回复，有时可能还需要做出修改 & 再次提交。需要注意的是 Flink 社区不建议使用 git squash 将多次提交进行合并压缩，因为这会丢失掉历史改动记录，建议修改后直接 append 到原来的 Commits 上即可。有时这一步可能会反复多次 & 会有多个 Committers 参与，直到提交者和 Committers 达成一致。对于 Contributor 来说整个 PR 到这一步就结束了，后续 Committer 会将其合并到 master 分支并关闭 PR。

简要总结一下，对于 contributor 来说完整提交 PR 的步骤如下所示。

Step1：在 JIRA 上认领感兴趣的 Issue，请 Committer 指派给自己。 Step2：完成 Issue 任务，做提交前的检查。 Step3：按规范填写 Commit 信息，并提交到远程私人仓库。 Step4：按规范填写 PR 信息，等待 Committer review。 Step5：处理 Committers 的意见，有时包括修改代码，重复此步骤直到 Committers 一致认为改动没有问题。

恭喜你已经成为了 Flink Contributor！Flink 每个版本的 Release Announcement 都会有一项 List of Contributors 列出所有贡献者的名单，同时 GitHub 贡献者页面上会列出历史累计 top 100 的贡献者名单。

image

如何成为优秀的 Contributor

提交第一个 PR 只是万里长征的第一步，那如何成为优秀的 Contributor 乃至 Committer 呢？下面总结了三个 tips 或许可以帮到你。

1. 积极参与用户答疑

image

Flink 社区非常鼓励能有更多的人参与到用户邮件列表中来，2019 年 Apache 财报显示 Flink 社区的邮件列表活跃度位列第一。社区每月都会统计各个邮件列表中积极回答问题的贡献者，会从这些活跃的贡献者中寻找潜在的 Committer 候选人。

2. 代码质量赢得社区信任

对于代码贡献者，最佳实践是：

• 遵循 Code style 规范，在 IDEA 配置 checkstyle.xml 随时检查，避免 PR 中出现 style 不规范等低级问题。

• 认真填写 PR 描述模板，尤其是“Brief change log” 部分，可参考 https://github.com/apache/flink/pull/7264 和 https://github.com/apache/flink/pull/10013

• 任何新增功能都要有测试覆盖，倾向于单元测试，而不是集成测试。

• 任何新增功能都要同步覆盖文档，中英文文档都需要更新或建立 Issue。

• 关注 Azure 实验室的测试结果。

3. 具有社区意识

最后一点，Contributor 或者 Committer 的头衔除了给我们个人带来“职业光环”外，更重要的是带来一份责任感，发自内心地帮助社区变得更好。比如不挑活、帮助新人成为贡献者、帮助 review 新增 PR（Review指南）等等。

最后，借用「小王子」里的经典台词 “It is the time you wasted on your rose that makes your rose important.” 祝大家在成为优秀 Contributor 的路上持续前进。

作者：伍翀（云邪），Apache Flink PMC，阿里巴巴技术专家

原文链接

本文为阿里云原创内容，未经允许不得转载。