码住!Flink Contributor 速成指南

用户头像
Apache Flink
关注
发布于: 2020 年 09 月 30 日

本文整理自 Apache Flink PMC 伍翀(云邪)直播分享,旨在为具备一定大数据基础、对 Flink 社区发展感兴趣的同学提供参与贡献的一些经验和流程。



为什么要参与开源社区



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



flink-why-contribute



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-contribution-way



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



flink-community-over-code



为什么呢?因为开源项目的良性发展并不是简单地依靠狂怼代码,没有社区的开源项目,其源码会一直停留在「孤芳自赏」阶段。“我有一个想法,这是我的代码”可能是最糟糕的贡献方式,因为在没有任何文档的情况下 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 模式。



  1. 加入自己感兴趣的 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 时使用的邮箱。



flink-contribute-preparation-jira



  • 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-repo-name} https://github.com/${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) 流程。不过在起飞前,我们需要先了解翻译规范[4],这里简要总结三点:



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

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

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



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



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



flink-contribute-demo-assign-phase



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



flink-contribute-demo-translate-phase



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



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



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

./run.sh



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



./build docs.sh -p



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



flink-contribute-demo-compile-phase



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



git checkout -b installation-translate



Flink 社区对 Commit Message 的格式有一定要求,一般是

[${jira-issue-id}][${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 页面链接[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(改动是否需要新文档)



flink-contribute-demo-pull-request-phase



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



flink-contribute-announcement



如何成为优秀的 Contributor



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



1. 积极参与用户答疑



flink-contribute-user-email



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指南[6])等等。



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



参考链接:



[1]https://flink.apache.org/contributing/code-style-and-quality-preamble.html

[2]https://flink.apache.org/community.html#mailing-lists

[3]https://gist.github.com/wuchong/ad6a3bd241aca0e04eef93ae71fba73b

[4]https://cwiki.apache.org/confluence/display/FLINK/Flink+Translati

on+Specifications

[5]https://issues.apache.org/jira/browse/FLINK-17939

[6]https://flink.apache.org/contributing/reviewing-prs.html

[7]从0到1,如何参与Flink社区

https://www.bilibili.com/video/BV1kK411577L

[8]如何成为一个合格的ASF贡献者

https://enjoyment.cool/2020/04/16/走进ASF系列-如何成为一个合格的ASF贡献者-Contributor/

[9]如何从小白成长为 Apache Committer?

http://wuchong.me/blog/2019/02/12/how-to-become-apache-committer/



用户头像

Apache Flink

关注

Apache Flink 中文社区 2020.04.29 加入

公众号:Flink中文社区 Apache Flink 官方帐号,Flink PMC 维护

评论

发布
暂无评论
码住!Flink Contributor 速成指南