• 如果您觉得本站非常有看点,那么赶紧使用Ctrl+D 收藏吧

![image.png](/img/bVcHqGd)码住!Flink Contributor 速成指南

互联网 diligentman 1周前 (10-15) 9次浏览

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

作者:伍翀(云邪),Apache Flink PMC,阿里巴巴技术专家
整理者:陈婧敏(清樾)

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

为什么要参与开源社区

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

![image.png](/img/bVcHqGd)码住!Flink Contributor 速成指南

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.png](/img/bVcHqGd)码住!Flink Contributor 速成指南

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

![image.png](/img/bVcHqGd)码住!Flink Contributor 速成指南

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

2. 准备工作

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

Flink 社区每天来往的邮件非常多,有效整理归档可以帮忙自己快速定位相关 topic,云邪在这里分享了他的 Gmail 收件规则 _https://gist.github.com/wuchong/ad6a3bd241aca0e04eef93ae71fba73b_,可作为参考。![image.png](/img/bVcHqGd)码住!Flink Contributor 速成指南

  • 关注 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.png](/img/bVcHqGd)码住!Flink Contributor 速成指南
  • 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) 流程。不过在起飞前,我们需要先了解翻译规范,这里简要总结三点:

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

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

Step1:申请成为某个 JIRA Issue 的 Assignee。由于这里是演示任务,所以我们打开事先准备好的翻译任务 FLINK-17939 Translate “Python Table API Installation” page into Chinese,将它 assign 给自己(云邪)。
![image.png](/img/bVcHqGd)码住!Flink Contributor 速成指南

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

![image.png](/img/bVcHqGd)码住!Flink Contributor 速成指南

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

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

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

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

./build docs.sh -p

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

![image.png](/img/bVcHqGd)码住!Flink Contributor 速成指南

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 页面链接 [https://github.com/apache/flink/pull/12343](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.png](/img/bVcHqGd)码住!Flink Contributor 速成指南

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.png](/img/bVcHqGd)码住!Flink Contributor 速成指南

如何成为优秀的 Contributor

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

1. 积极参与用户答疑

![image.png](/img/bVcHqGd)码住!Flink Contributor 速成指南

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 的路上持续前进。

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


喜欢 (0)