開發與維運

如何從 0 到 1 參與 Flink 社區？

2020-06-09

整理：許世偉、秦佳奇（Flink 社區志願者）
校對：秦佳奇、許世偉（Flink 社區志願者）

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

  • 參與開源社區的意義
  • 參與開源社區的原則
  • 如何參與 Flink 社區
  • 如何提交第一個 PR

Tips：點擊下方鏈接可回顧更多社區成長類教程～

社區成長：
https://ververica.cn/developers/flink-training-course3/

本文首先介紹為何要參與開源社區以及在參與開源社區的過程中需要注意什麼，然後重點介紹如何參與 Flink 社區以及在社區裡面提交 PR 的整個流程。

一、參與開源社區的意義

640 1.png

目前很多大公司都紛紛擁抱開源，從最初只是開始參與開源社區，到近年科技巨頭們又陸續將自己的一些項目開源化。作為一個碼農來說，參與開源社區肯定對於自己的職業發展是有著巨大好處的。

另外，參與開源社區，你可以和相關領域裡面最優秀的人一起工作交流，快速的提升自己。不管在技術討論、還是貢獻代碼方面，所有的過程都是公開的。參與到開源社區的討論交流中，我相信你看到的不僅是最終代碼所呈現出來的結果，而且還能瞭解到更多的設計思想，做到知其然，知其所以然。在社區中，每個人都希望將自己最好的一面給展示出來，這個無疑是促進自身不斷進步的動力。

在享受開源社區帶給我們好處的同時，我們也可以反哺開源社區。改了某幾行代碼，或者修正了文檔上面某個小錯誤，這些都是在為開源社區貢獻自己的力量。我們與社區之間要相互 build trust，可以從簡單的貢獻做起。不要因為對某個領域不熟悉或者說貢獻太小而有放棄的想法，這是不太對的。

當我們為開源社區做的貢獻足夠多之後，可能會得到社區的認可，成為社區的 Contributor、Committer、PMC、Apache Member 等等，這是社區對我們個人能力的一種認可。

總結而言，參與開源的意義在於：

  • 順勢而為
  • 無國界導師
  • 為世界帶來微小而美好的變化
  • 業界身份證

二、參與開源社區的原則

參與開源社區，有兩個基礎且重要的原則需要大家注意：

  • 公開溝通

公開溝通是參與開源社區很重要的原則。任何問題及所有的討論記錄最好都公開化，做到可追溯，儘量避免私下討論，這樣才能更好地發揮社區的力量。

  • 保持尊重

在社區裡面，要保持相互尊重。社區的貢獻是以自願為基本原則的，在社區的討論中要避免情緒化，絕對禁止人身攻擊。

三、如何參與 Flink 社區

1.訂閱郵件列表

表1.jpg

關於郵件列表的更多具體信息：https://flink.apache.org/community.html#mailing-lists

參與 Flink 社區，先從訂閱郵件列表入手，上面的表格是 Flink 社區常用的幾個郵件及郵件用途信息，建議大家先訂閱這幾個郵件。訂閱方式如下：

1.發送郵件到相應的郵件列表進行訂閱
    [email protected]
    [email protected]

2.回覆確認郵件

2.參與用戶郵件列表討論

■ 2.1 用戶郵件提問注意事項

  • 事先搜索有無類似問題

這幾個地方可能有你想要的答案：

Apache Pony:
https://lists.apache.org/[email protected]
Nabble:
http://apache-flink-user-mailing-list-archive.2336050.n4.nabble.com/
StackOverFlow:
https://stackoverflow.com/questions/tagged/apache-flink

  • 問題描述應儘可能詳細

例如：使用的 Flink 版本、planner、和問題相關的配置、異常 log、復現問題的步驟；如果可能的話，提供可復現問題的最小功能代碼（儘可能去除無關代碼）；儘量不要在郵件裡直接貼圖片，如果確實有需要，先將圖片上傳到外部網站，然後把圖片鏈接貼到郵件裡。

  • 避免將 Flink 使用問題發到開發郵件
  • 儘量用英文在 user 郵件中討論

■ 2.2 用戶郵件提問正反面示例

  • 反面示例
❌ 缺少Flink版本
❌ 缺少所用planner
❌ 缺少示例代碼

640 2.png

  • 正面示例
✅ 所用Flink版本
✅ 作業併發度
✅ 示例代碼
✅ sink的輸出結果
✅ 詳細描述了疑惑的地方

640 3.png

■ 2.3 用戶郵件回答問題注意事項

  • 先弄清楚問題再回答（如果對方提供信息不夠，可追問清楚）
  • 參與任何自己感興趣的話題，當然最好是自己熟悉的領域
  • 有不確定的地方，可以抄送可能對這個問題更熟悉的人
  • 回答應該條理清晰、儘可能全面

3.參與開發郵件列表討論

  • 大功能、先討論、後開發 [詳見：討論 -> 投票 -> 開發 -> 合併]
  • 郵件標題格式 “[DISCUSS] XXX”
  • 選擇熟悉或感興趣的領域，參與討論

四、如何提交第一個 PR

1.註冊 Apache JIRA 賬號 / GitHub 賬號

表2.jpg

2.下載 Flink 代碼

■ 2.1 Fork Flink 項目到自己的 github 賬號下

640 4.png

■ 2.2 Clone Apache Flink 的代碼倉庫到本地

git clone https://github.com/apache/flink.git

■ 2.3 添加自己 github 賬號下 cloned 的 Flink 倉庫

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

這裡的 dianfu 這個名字是隨便起的，它在本地代表遠程倉庫的別名。

3.開發環境準備

■ 3.1 開發環境

表3.jpg

■ 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

  • 標題清楚
  • 需要標清楚涉及的模塊、出現問題的版本
  • 問題描述應儘可能詳細
  • 不要使用中文

640 5.png

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/ 可以看到文檔效果

640 6.png

■ 5.4 提交代碼之前

對於 Java 代碼需要在所修改模塊下執行：

mvn clean install

對於 Python 代碼需要在 flink-python 模塊下：

./dev/lint-python

6.提交 PR

■ 6.1 Commit Message

  • 格式：FLINK-XXX描述
  • 每個 commit 應該邏輯獨立

640 7.png

■ 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 的提交頁面。

640 8.png

PR 的提交頁面，包括了這幾種信息：

PR提交到哪裡：官方flink倉庫的branch名字
PR來自哪裡：個人flink倉庫的branch名字
Able to merge：是否有衝突
PR標題：[FLINK-XXX][python] Support converting ...
PR描述信息

640 9.png

當 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 頁面，也能看到貢獻的記錄。

640 10.png

五、其它參與方式

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

Flink 社區直播及 Meetup 嘉賓正在徵集中，如果您有想與大家分享的主題，填寫下方問卷即可與社區相關同學聯繫：

https://survey.aliyun.com/apps/zhiliao/SJQZ5xRkK

2.文檔貢獻，比如文檔補充、糾錯、翻譯等

社區除文檔貢獻外，還有活動、直播、Meetup 等內容的文章整理，感興趣的同學可填寫下方問卷留下您的聯繫方式，小松鼠大本營期待您的加入！

https://www.wenjuan.com/s/InAJjm6/

3.檢查即將發佈的 Release

4.代碼 Review

除此之外，您還有多種方式可參與社區，大家請關注社區最新動態～

總體而言，本文主要向大家重點介紹瞭如何參與 Flink 社區以及在 Flink 社區提交 PR 的整個流程。接下來，大家可以從自己感興趣的模塊開始，積極地參與 Flink 社區，提升自身能力。或許，下一個 Committer 就是你！

作者介紹：

付典，Apache Flink Committer，阿里巴巴技術專家，目前專注於 PyFlink 項目的開發。

Leave a Reply

Your email address will not be published. Required fields are marked *