关于flink:码住Flink-Contributor-速成指南

本文整顿自 Apache Flink PMC 伍翀（云邪）直播分享，旨在为具备肯定大数据根底、对 Flink 社区倒退感兴趣的同学提供参加奉献的一些教训和流程。

为什么要参加开源社区

作为 Apache Flink PMC 的云邪依据本身经验总结了参加开源社区倒退的三个次要起因。

1. 开源精力

「自在」堪称是开源精力的外围，自在意味着世界范畴内自由自在的交换分享与思维的碰撞。云邪自述“拿我集体来说，我在大学阶段正好经验了 Hadoop、Spark 大火的阶段，那时候就特地神往做开源，特地崇拜能熟读源码的大神，特地心愿本人有一天也可能写很多开源代码，让本人写的代码被上万的用户应用。所以对于我来说，参加开源就像是一个喜好一样，违心为之付出工夫和致力。我也很幸运地在毕业后就接触上了开源社区。”

2. 技术成长

参加开源是晋升集体代码品质的好办法。开源社区对于代码和设计要求十分高，不像一些外部我的项目绝对随便。对于设计，Flink 社区有一套专门的 FLIP 机制，任何重大的奉献都会通过公开和粗疏的探讨。对于代码，Flink CTO 亲自写了 26 页的 Code style 指南 [1]，此外每次提交 PR 后也会收到 Committers 的 Review 倡议，所以继续地在开源社区里奉献代码，对于集体的零碎思维能力和代码能力都有很大晋升。

3. 职业规划

如果你在筹备跳槽或是公司外部降职，除了现有的 Title 外，参加开源社区的经验相对是一个加分项，因为开源产品自身就带有网红的标签，而参加其中则有助于进步本身的影响力 & 结识同行业的大牛们。开源奉献除了能间接地反映你的代码能力外，成为 Committer 甚至 PMC member 更能证实你的激情 & 毅力 & 沟通合作方面的 Soft skills（因为这须要你继续实现高质量的奉献，与社区其它成员独特合作，在有意见分歧的时候放弃凋谢敌对的态度 etc.）。

如何成为 Contributor

1. 奉献路径

不论初衷是什么，Flink 都十分欢送大家一起建设和欠缺社区。在开始具体的奉献步骤之前，咱们先简要介绍一下参加奉献的几种路径，以及 Clarify 对于开源奉献的一些固有印象。

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

为什么呢？因为开源我的项目的良性倒退并不是简略地依附狂怼代码，没有社区的开源我的项目，其源码会始终停留在「打成一片」阶段。“我有一个想法，这是我的代码”可能是最蹩脚的奉献形式，因为在没有任何文档的状况下 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）。对于邮件列表的更多信息能够参考 [2]。发送邮件到相应的邮件列表并回复确认信息即可订阅。

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

Flink 社区每天来往的邮件十分多，无效整顿归档能够帮忙本人疾速定位相干 topic，云邪在这里分享了他的 Gmail 收件规定 [3]，可作为参考。

• 关注 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 时应用的邮箱。

• Fork Flink 仓库 & 下载 Flink 源码

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

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

接着增加本人 fork 的仓库用于提交开发分支：git remote add ${your-repo-name} https://github.com/${your-github-id}/flink.git。

E.g. 云邪的配置 git remote add my https://github.com/wuchong/fl…。

开始第一个 Pull Request 之旅

对于参加社区的起步者，翻译模块通常是“ROI”最高的抉择。因为它不仅易上手而且笼罩了规范奉献流程，分分钟让你变身 Apache Flink Contributor。上面咱们将通过一个中文翻译例子来展现残缺的 Pull Request（以下简称 PR）流程。不过在起飞前，咱们须要先理解翻译标准 [4]，这里简要总结三点：

• 应用纯文本工具进行翻译
• 汉字与英文、数字之间须要有空格
• 中文文档链接须要在相应英文文档的 baseUrl 后增加 zh 适配

在上述筹备工作实现后，咱们就进入激动人心的实战阶段了。

Step1： 申请成为某个 JIRA Issue 的 Assignee。因为这里是演示工作，所以咱们关上当时筹备好的翻译工作 FLINK-17939 Translate “Python Table API Installation” page into Chinese[5]，将它 assign 给本人（云邪）。

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

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

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

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

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

./build docs.sh -p

而后关上 localhost:4000 切换到中文版就能够查看渲染后的文档，比方排版格局及页面里的超链接是否失常关上等等，确认无误后就能够提交了。留神，要为指向其余文档的超链接做中文适配。

Step3： 提交阶段筹备。最佳实际是创立一个用于提交的分支，将改变提交到这个分支上。比方这里创立一个叫 installation-translate 的分支并切换过来。

git checkout -b installation-translate

Flink 社区对 Commit Message 的格局有肯定要求，个别是 [${jira-issue-id}][${affected-component}] ${jira-issue-title}。

以 Demo 为例，就是 FLINK-17939 Translate “Python Table API Installation” page into Chinese

在本地提交后就能够通过上面的命令把改变推送到本人 fork 的近程公有仓库。

git push my installation-translate

Step4： 筹备 PR。在将变更推送到本人 fork 的近程仓库后，Github 会主动创立一个新的 PR 并返回 PR 页面链接 [4]，在此基础上须要填写如下信息，从而不便 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（改变是否须要新文档）

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 的贡献者名单。

如何成为优良的 Contributor

提交第一个 PR 只是万里长征的第一步，那如何成为优良的 Contributor 乃至 Committer 呢？上面总结了三个 tips 或者能够帮到你。

1. 积极参与用户答疑

Flink 社区十分激励能有更多的人参加到用户邮件列表中来，2019 年 Apache 财报显示 Flink 社区的邮件列表活跃度位列第一。社区每月都会统计各个邮件列表中踊跃答复问题的贡献者，会从这些沉闷的贡献者中寻找潜在的 Committer 候选人。

2. 代码品质博得社区信赖

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

• 遵循 Code style 标准，在 IDEA 配置 checkstyle.xml 随时查看，防止 PR 中呈现 style 不标准等低级问题。
• 认真填写 PR 形容模板，尤其是“Brief change log”局部，可参考 https://github.com/apache/fli… 和 https://github.com/apache/fli…
• 任何新增性能都要有测试笼罩，偏向于单元测试，而不是集成测试。
• 任何新增性能都要同步笼罩文档，中英文文档都须要更新或建设 Issue。
• 关注 Azure 实验室的测试后果。

3. 具备社区意识

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

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

参考链接：

[1]https://flink.apache.org/cont…
[2]https://flink.apache.org/comm…
[3]https://gist.github.com/wucho…
[4]https://cwiki.apache.org/conf…
[5]https://issues.apache.org/jir…
[6]https://flink.apache.org/cont…
[7] 从 0 到 1，如何参加 Flink 社区 https://www.bilibili.com/vide…
[8] 如何成为一个合格的 ASF 贡献者 https://enjoyment.cool/2020/0…
[9] 如何从小白成长为 Apache Committer?http://wuchong.me/blog/2019/0…