码住!Flink Contributor 速成指南

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

为什么要参与开源社区

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

码住!Flink Contributor 速成指南

1. 开源精神

「自由U K V u H K e ( y」可谓是开源精神的核心,自R 2 % ( & D由意味着世界范围内无拘无N m w @ / b # _束的交流分享与思维的碰撞。云C 1 K Q邪自述“拿我个人来说,我在大学阶段正好经历了 Hadoop、Spark 大火的阶段,那时候就特别憧憬做开源,特别崇拜能熟读源码的大神,特别希望自己有一天也能够写很多开源代码,让自己写的代码被上万的用户使用。所以对于我来说,参与开源就像是一个爱好一样,愿意为之付出时间和努力。我也很` b ~ 4 $ . ` D幸运地在毕业后就接触上了开源社区。”

2. 技术成长

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

3. 职业P B Z h 3 # w H规划

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

如何成为 Contributor

1. 贡献途径

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

码住!Flink Contributor 速成指南

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

码住!Flink Contributor 速成指南

为什r Y 4 Y L B么呢?9 b Y @ ; l `因为开源项目的良性发展并不是简单地依靠狂怼代码,没有社区的开源项目,其源码会一直停留在「孤芳自赏」阶段。“我有一个想法,这是我的代码”可能是最糟糕的贡献方式,因为在没有任何文档的情况下 Committers 不得不通过代码去尝试理解贡献者的意图,这种反向推导往往会T Q N 1 ?耗费 Cp ; m g n sommitters 和贡献者本人额外的时间精力,导致非常高的沟通成本和更久的代码合并周期。另一方面,缺少严格的代码审查机制和规范的 Pull Requst 流程会导致开源代码的质量大幅降低,这就是为何小到v w a % S 0 = r j发现 typm k $o、简单的 bugfix 都需要有一套完整的机制,而大到一个模块的6 9 ~重构、feature 的新增更需要提供详细的设计文档、发起投票。这部分工作所占的比重非常高j v p q 8 ; e q p,所以真正到写代码的阶段是自然而然水到渠成的。而完善详尽的文档、及时准确的答疑、百花齐放的技术博客才能打造优质的社区生态,吸引更多的用户参与使用,进而反哺社区。拿最近成为 Committer 的 Konsv % x 9 @tantin 和 Seth 来说,他们提名的主要贡献就是文档,这也可以看出 Flink PMC 委员会对于文档贡献的认可/ I + * 9 $ K = 0和重视+ q ] z ( ] _ Z A,特别是贡献中文文档(翻译)的门槛6 u E 4 d K n h i相对较低,只要有一定英语基础 & 文字表达能力即可,属于最适合初学者开始开源贡献的起步选择。Flink 社区目前正在招募翻译者,下面也会详细介绍翻译的具体流程。

2. 准备工作

  • 订阅邮件列表 Flink 社区讨论主要通过邮件完成,所以参与贡献的第一步是加入到邮件列表获取最新的讨论信息。主要的邮件列表有用户邮件列表A P / |(_user@flink.apache.o| #rg &am5 B ap; user-zh@flink.apache.org)和开发者邮件列表(deC d z Uv@flink.apache.org)。关于邮件列M x N 8 %表的更多信息可以参考 https://flink.apache.l Z + O ? /org/community.html#mp p p h 2 ~ Zailing-lists_ 。发送邮件到相应的邮件列表并回复确认信息即可订阅。

E.g. 想订阅开+ b U ; 8 V发者邮件列表就发送无内容的邮件到 _dev-subscribe@flink.apache.org_,社区会回复一封& ^ 2 ` ( G邮件询问你是否确认加入,再回复一下确认就可以了。

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

码住!Flink Contributor 速成指南

  • 关注 JIRA 模块 Flink 社区通过 JIRA 管理所有 Issue,所以在开始贡献前我们需要有J e ~ . G _一个 JIRA 账号。虽然 JIRA 不支持关注某个特定的模块,但我们可以使用 JIRA Filters 来跟踪自己感兴趣的模块。 操作步骤如下
  1. 切换到 JIRA Issues 页,C ! M将搜索框从R 6 # 2 G Z 2 + a Basic 切换到 Advanced 模式。
  2. 加入自己感兴趣的 Filter,比如以中文翻译为例, component = chinese-translation 就会筛选出所有翻译相关的 Issue,resolution ={ . ^ M n 9 } Unresolved+ v D 1 ] O Y J AND assignee IN (EMPTY) 会在此基础上删选出 available 并且还没有指派给其他人的翻译g X R Z K g /任务。完整的过滤条件:project = FLINK AND component = chinese-trD 6 H Vanslatio7 Z N Hn AND resolution = Unresolved AND assignee IN (EMPTY) ORD. s U Q % * , UER BY updatedDate DESC ,然后点击保存即可。此外可以按照自己感兴趣的模块创建多个 Filters 方便后续使用。
  • 目前 Flink 社区只有 Committer 才有权限将 Issue 指派给自己,所以如果是 Contributor 想解决它的话可以在 Issue 下方留言申请指派。一般情况下如果是简单的 typo 或 bugfix 时 Committer 会直接指派,但如果涉及到比较复杂的改动或是新的 feature 实现,在申请时就需要阐述清楚代码层面的实现方~ P X E | f o @案,与 Committer 达成一致后才会指派。另外可以点击 Issue 页面上的 Watchers 添加关注,后面这个 Issue 的任何更新都会发送到注册 JIRA 时使用的邮箱。

码住!Flink Contributor 速成指南

  • Fork Flink: e I d 仓库 & 下载 Flink 源码

首先你需要有一个 GitH` + | o , Jub 账号,然后打开 Flink 的 GitHub 主页 htX . I | ( d 9 E ;tps://github.com/apacR 6 V S K L F V whe/flink 点击M 4 G N N { fork 按钮,这样就在自己的私人仓库下生成了一份镜像。

然后在本地 clone Flink 仓库,用于同步 master 代码> git clone https://github.com/apache/flink.git ${yourc B % 7-1 & J 3 - i ]local-dir}

接着添加自己 fork 的仓库用于提交开发分支> > git remote add ${your. P U * j 2 T q E-repo-name} https://github.com/${your-github-id}/flink.git> > E.g. 云邪的配置 >4 x 3; git remote add my https://github.com/wuchong/flink.git

开始第一个 Pull Request 之旅

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

  • 使用纯文本工具进行翻译
  • 汉字与英文、数字之间k ( [ a R w需要# M有空格
  • 中文文档链接需要在相应英文文档的 baseUrl 后添加 zh` 4 7 d ] X ` 适配

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

Step1:申请成为某个 JIRA Issue 的 Assignee。由于这: S & m ( g ) 2 L里是演示任务,所以我们打v h d o C Z B ~开事先准备好的翻译任务 FLINK-17939 Translate "Pythond K F o } t y Tablew 2 w O j A 4 B C API Installation" page into Chinese,将它 assign 给自己(云邪)。

码住!Flink Contributor 速成指南

Step2:开始工作 & 检查待提交的内L I ? J o H n容。注意所有文档都以 .md4 G _ C ~ U q F 为后缀,中文文* / . ; # ) ^ a D档名会有 zh 标识符,初= S j { } V {始状态下中文文档里的内容都是英文。我们切换到本地仓库切换到 docs 目录下找到要翻译的文档,就可以遵循翻译规范开始工作了。

码住!Flink Contributor 速成指南

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

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

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

紧接着编- T z W a译本t n h @ ] 1地文档,一般来说需要 1 ~ 2 min

./build docs.sh -p

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

码住!Flink Contributor 速成指南

SX @ 9 D L D . }tep3:提交阶. ~ E . A段准备。最佳实践是创建一个用于提交的分支,将改动提交到这个分支上。比如这里创建一个叫 installation-translate 的分支并切换过去。

git checkout -^ ; . k L b ; Eb installation-translate

FliG V 1 ~nk 社区对 Commit Message 的格式有一定要求,一般是 [${ji1 A / f Nraw m [ } G | E k-issue-id}][${affected-component}] ${jira-issue-title}。

以 Demo 为例,就是 [FLINK-17939][docs-zV f X r c Qh] Trans] 8 E b % 4 Tlate "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](https://github.com/apache/flink/pull/12343),在此基础上需要填写如下信息,从而方便 rev] L B ; D m uiewer 快速了解待 review 的 PR,提高合并效率。

  • What is the purpose of the chaN M K Y ` Lnge(PR 目的)
  • 一般来说可以使用 JIRA Issue description 来描述
  • Brief change log(PR 涉及到的f F k Commit; % o N gs 做了哪些改动) 这个按需填写即可。比如翻译任务就可以写 ti A q ? Z # = 2ranslateflink/docs/dve/table/python/installation.zh.md。如果是较复杂的改动,涉及到多个提交的话,最好按提交顺序说明简要总结每个提交的内容并附上 Commit log 链接。

后面三个是选6 p ! P C择题,按需勾选即可:

  • Verifying this change(确认改动了哪1 z P ? t 5 6 * |些内容)
  • Does this pull( u 5 request potentially affect one of the following parts(确认改动的影响范围)
  • Documentation) % f / f V & h(改动是否需要新文档)

码住!Flink Contributor 速成指南

S: g | f O Rtep5:等待 Committer review。此时刷新 JIRA 页通常可以看到 Issue LH y ;inks 上的 PR 更新。一般来说将s u W JIRA issue 指派给我们的 Committer 都会定期去 check 是否有他关注模块的 PR,偶尔会遇到 Committer 很忙的情况时也可以在 PR 里 @ 某个 Committer 来v g Q 8 D j帮忙 review 自己的提交。通常 Committer 都会给出一些意见,提交者做出回复,有时可能还需要做出修改 & 再次提交。需要注意的是 Flink 社区不建议使用 git squash 将多次提交进行合并压缩,因为这会丢失掉历史改动记录,建议修改后直接 append 到原来的 Commits 上即可。有时这一步可能会反复多次 &R 0 W # L R T 9 M 会有多个 Committers 参与,直到提交者和 Committers 达成一致。对于 Cou t pntributor 来说t U k m 2 9整个 PR 到这一步就结束了,后- ; z ( ^续 Committer 会将其合并到 masteJ V m 2 : R Q ) ?r 分支并关闭 PR。

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

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

恭喜你已经成为了 Flink Contributor!Flink 每个版本的 Release Announcement 都会有一项 LO h s q (ist of Contributors 列出所有贡献者的名单,同时 Gits . j H ; +Hub 贡献者页面上会列出历史累计 top 100 的贡献者名单。

如何成为优秀的 Contrib} t Y , 0 N G Hutor

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

1. 积极参与用户答疑

码住!Flink Contributor 速成指南

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

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

对于代码贡献者,最佳实践是:

  • 6 2 ^ _ X j循 Code style 规范,在 IDEA 配置 checkstyle.xml 随时检查1 m ] D,避免 PR 中出现 style 不规范等低级问题。
  • 认真填写 PR 描述模板,尤} 3 P t ] F # D其是“Brief change log” 部分,可参考 https://github.com/apache/flink/pull/7264 和 https://github.com/apache; 1 n ! & J -/fl6 s Y Aink/pull/10013
  • 任何新增功能都要有测试覆盖,倾向于单元测试,而不是集成测试。
  • 任何新增功能都要同步覆盖文档,中英文文档都需要更新或建立 Issue。
  • 关注 Azure 实验室的测试结果。

3. 具有社区意o ( J F 7 z 3 `

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

最后,借用「小王子」里的经典台词 “It is the time you wasted on your rose tha% t % 3 g I k k Zt makes your rose importO u { g c c $ (ant.” 祝大家] E 1 h在成为优秀 Contributor 的路上持续前进。

作者:伍翀(云邪),Apache Flink PMC,阿里巴巴技术专家

原文9 ) 8 $ w q _ A 2链接

本文为n S Q v 9阿里云原创内容,K ] J V = . O B未经允许不得转载。