如何从-0-到-1-参与-Flink-社区

整理：许世伟、秦佳奇（Flink 社区志愿者）
校对：秦佳奇、许世伟（Flink 社区志愿者）

摘要：本文根据 Apache Flink 系列直播整理而成，由 Apache Flink Committer，阿里巴巴技术专家付典分享。主要内容如下：

• 参与开源社区的意义
• 参与开源社区的原则
• 如何参与 Flink 社区
• 如何提交第一个 PR

Tips：点击下方链接可回顾更多社区成长类教程～

社区成长：
https://ververica.cn/develope…

本文首先介绍为何要参与开源社区以及在参与开源社区的过程中需要注意什么，然后重点介绍如何参与 Flink 社区以及在社区里面提交 PR 的整个流程。

一、参与开源社区的意义

目前很多大公司都纷纷拥抱开源，从最初只是开始参与开源社区，到近年科技巨头们又陆续将自己的一些项目开源化。作为一个码农来说，参与开源社区肯定对于自己的职业发展是有着巨大好处的。

另外，参与开源社区，你可以和相关领域里面最优秀的人一起工作交流，快速的提升自己。不管在技术讨论、还是贡献代码方面，所有的过程都是公开的。参与到开源社区的讨论交流中，我相信你看到的不仅是最终代码所呈现出来的结果，而且还能了解到更多的设计思想，做到知其然，知其所以然。在社区中，每个人都希望将自己最好的一面给展示出来，这个无疑是促进自身不断进步的动力。

在享受开源社区带给我们好处的同时，我们也可以反哺开源社区。改了某几行代码，或者修正了文档上面某个小错误，这些都是在为开源社区贡献自己的力量。我们与社区之间要相互 build trust，可以从简单的贡献做起。不要因为对某个领域不熟悉或者说贡献太小而有放弃的想法，这是不太对的。

当我们为开源社区做的贡献足够多之后，可能会得到社区的认可，成为社区的 Contributor、Committer、PMC、Apache Member 等等，这是社区对我们个人能力的一种认可。

总结而言，参与开源的意义在于：

• 顺势而为
• 无国界导师
• 为世界带来微小而美好的变化
• 业界身份证

二、参与开源社区的原则

参与开源社区，有两个基础且重要的原则需要大家注意：

• 公开沟通

公开沟通是参与开源社区很重要的原则。任何问题及所有的讨论记录最好都公开化，做到可追溯，尽量避免私下讨论，这样才能更好地发挥社区的力量。

• 保持尊重

在社区里面，要保持相互尊重。社区的贡献是以自愿为基本原则的，在社区的讨论中要避免情绪化，绝对禁止人身攻击。

三、如何参与 Flink 社区

1. 订阅邮件列表

关于邮件列表的更多具体信息：https://flink.apache.org/comm…

参与 Flink 社区，先从订阅邮件列表入手，上面的表格是 Flink 社区常用的几个邮件及邮件用途信息，建议大家先订阅这几个邮件。订阅方式如下：

1. 发送邮件到相应的邮件列表进行订阅
    xxx-subscribe@flink.apache.org
    xxx-unsubscribe@flink.apache.org

2. 回复确认邮件

2. 参与用户邮件列表讨论

■ 2.1 用户邮件提问注意事项

• 事先搜索有无类似问题

这几个地方可能有你想要的答案：

Apache Pony:
https://lists.apache.org/list…
Nabble:
http://apache-flink-user-mail…
StackOverFlow:
https://stackoverflow.com/que…

• 问题描述应尽可能详细

例如：使用的 Flink 版本、planner、和问题相关的配置、异常 log、复现问题的步骤；如果可能的话，提供可复现问题的最小功能代码（尽可能去除无关代码）；尽量不要在邮件里直接贴图片，如果确实有需要，先将图片上传到外部网站，然后把图片链接贴到邮件里。

• 避免将 Flink 使用问题发到开发邮件
• 尽量用英文在 user 邮件中讨论

■ 2.2 用户邮件提问正反面示例

• 反面示例

❌ 缺少 Flink 版本
❌ 缺少所用 planner
❌ 缺少示例代码

• 正面示例

✅ 所用 Flink 版本
✅ 作业并发度
✅ 示例代码
✅ sink 的输出结果
✅ 详细描述了疑惑的地方

■ 2.3 用户邮件回答问题注意事项

• 先弄清楚问题再回答（如果对方提供信息不够，可追问清楚）
• 参与任何自己感兴趣的话题，当然最好是自己熟悉的领域
• 有不确定的地方，可以抄送可能对这个问题更熟悉的人
• 回答应该条理清晰、尽可能全面

3. 参与开发邮件列表讨论

• 大功能、先讨论、后开发 [详见：讨论 -> 投票 -> 开发 -> 合并]
• 邮件标题格式“[DISCUSS] XXX”
• 选择熟悉或感兴趣的领域，参与讨论

四、如何提交第一个 PR

1. 注册 Apache JIRA 账号 / GitHub 账号

2. 下载 Flink 代码

■ 2.1 Fork Flink 项目到自己的 github 账号下

■ 2.2 Clone Apache Flink 的代码仓库到本地

git clone https://github.com/apache/fli…

■ 2.3 添加自己 github 账号下 cloned 的 Flink 仓库

git remote add dianfu https://github.com/dianfu/flink.git

这里的 dianfu 这个名字是随便起的，它在本地代表远程仓库的别名。

3. 开发环境准备

■ 3.1 开发环境

■ 3.2 构建项目

在项目根目录下构建，命令如下:

mvn clean install -DskipTests

构建完成后，出现 build-target 目录。

4. 创建 JIRA

■ 4.1 大功能、先讨论、再创建

在 Flink 里面所有大的功能或者是说涉及 API 的改动，都需要先创建 flip。再经过社区讨论，讨论通过之后才能进行开发。

■ 4.2 现存 JIRA

如果有 owner，需要先征求 owner 的同意
没有 owner，在 JIRA 上面 ping 相关模块的 committer，将 JIRA assign 给你（Contributor 没有权限 assign JIRA）。提交 PR 之后，需要 committer 进行 review

■ 4.3 新建 JIRA Flink JIRA

• 标题清楚
• 需要标清楚涉及的模块、出现问题的版本
• 问题描述应尽可能详细
• 不要使用中文

5. 代码开发

■ 5.1 开发注意事项

• 开发前请阅读 code style
• 避免引入新的依赖。若有，则依赖的 license 需要满足一些要求
• 避免引入新的 scala 文件
• 涉及 API 的修改，需要先讨论再修改
• 避免和当前 PR 无关的修改
• 逻辑上独立的修改，可拆分成不同的 commit，提交信息能反应出修改内容

■ 5.2 Test Case

• 能用 UT 的，尽量不要用 IT
• 参考已有 Test Case 的写法
• 不要过度测试

■ 5.3 注释、文档

• 文档风格
• 英文 / 中文文档都需要更新
• 中文文档里的链接应该指向其它中文文档
• 更新文档、实时查看

cd docs & sh build_docs.sh –p

访问 http://0.0.0.0:4000/ 可以看到文档效果

■ 5.4 提交代码之前

对于 Java 代码需要在所修改模块下执行：

mvn clean install

对于 Python 代码需要在 flink-python 模块下：

./dev/lint-python

6. 提交 PR

■ 6.1 Commit Message

• 格式：FLINK-XXX 描述
• 每个 commit 应该逻辑独立

■ 6.2 Push 到个人 GitHub 账号下 fork 的 Flink 仓库

git push dianfu branch_name
example：git push dianfu FLINK-16667

■ 6.3 Open PR

上一步 push 完之后，Fork 的 flink 项目会立马显示出刚才 push 的分支，然后点击右边的按钮 (Compare & pull request)，就会进入到 PR 的提交页面。

PR 的提交页面，包括了这几种信息：

PR 提交到哪里：官方 flink 仓库的 branch 名字
PR 来自哪里：个人 flink 仓库的 branch 名字
Able to merge：是否有冲突
PR 标题：[FLINK-XXX] Support converting ...
PR 描述信息

当 PR 提交之后，就会在对应的 JIRA 上面自动生成 PR 链接。

7. 测试实验室

■ 7.1 关注实验室的测试结果

当你提交一个 PR 之后，就会触发实验室进行测试。目前是有两个实验室的一个 Travis，一个是 Azure。这个是由于历史原因造成的，目前 Flink 实验室正从 Travis 迁移到 Azure。在迁移完成之前，PR 需要两个实验室都跑通过才能 merge。从下面的图中可以看到两个实验室测试都已通过【SUCCESS】。

■ 7.2 private 个人实验室

如果实验室测试结果失败，可以点击失败链接进入实验室，查看 log 详情。

8. 跟进 review 反馈更新 PR

■ 8.1 每一个 review comment 都应该处理

• 接受的 comment，直接在新的 commit 里修改即可
• 有不同意见的 comment 应该提出来，而不要默默忽略

■ 8.2 尽量追加 commit，而不是把新的 commit 和之前的 commit squash 到一起

■ 8.3 修改之后，push 到之前的 branch 即可

git push dianfu branch_name

■ 8.4 PR 时间较久，应先 rebase 最新的 master

  git checkout master
  git pull
  git checkout branch_name
  git rebase master
  git push dianfu branch_name -f

■ 8.5 关注更新之后的 PR 的测试结果

■ 8.6 在 PR 页面 ping 下 Reviewer

■ 8.7 PR merge 之后，关注下 build 邮件列表

■ 8.8 Flink contributors

如果你贡献多了之后，可以在 Flink contributors 这个页面里看到你的贡献，另外在个人的 github 页面，也能看到贡献的记录。

五、其它参与方式

1. 技术分享，比如直播、meetup、博客等

Flink 社区直播及 Meetup 嘉宾正在征集中，如果您有想与大家分享的主题，填写下方问卷即可与社区相关同学联系：

https://survey.aliyun.com/app…

2. 文档贡献，比如文档补充、纠错、翻译等

社区除文档贡献外，还有活动、直播、Meetup 等内容的文章整理，感兴趣的同学可填写下方问卷留下您的联系方式，小松鼠大本营期待您的加入！

https://www.wenjuan.com/s/InA…

3. 检查即将发布的 Release

4. 代码 Review

除此之外，您还有多种方式可参与社区，大家请关注社区最新动态～

总体而言，本文主要向大家重点介绍了如何参与 Flink 社区以及在 Flink 社区提交 PR 的整个流程。接下来，大家可以从自己感兴趣的模块开始，积极地参与 Flink 社区，提升自身能力。或许，下一个 Committer 就是你！

作者介绍：

付典，Apache Flink Committer，阿里巴巴技术专家，目前专注于 PyFlink 项目的开发。