作者：伍翀（雲邪），Apache Flink PMC，阿里巴巴技術專家
整理者：陳婧敏（清樾）
本文整理自 Apache Flink PMC 伍翀（雲邪）直播分享，旨在為具備一定大數據基礎、對 Flink 社區發展感興趣的同學提供參與貢獻的一些經驗和流程。
為什麼要參與開源社區
作為 Apache Flink PMC member 的雲邪根據自身經歷總結了參與開源社區發展的三個主要原因。
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 關於開源貢獻的一些固有印象。
說起開源貢獻可能大家的直觀反應就是貢獻代碼。不過在 Flink 社區中有非常多的參與貢獻的方式，包括文檔、翻譯、答疑、測試、以及代碼等，並且社區將文檔貢獻放在第一位，代碼貢獻放在最後。因為 Apache 社區對於代碼貢獻的態度是 Community Over Code，Flink CTO 更是親自發推說明代碼貢獻的“不重要性”。
為什麼呢？因為開源項目的良性發展並不是簡單地依靠狂懟代碼，沒有社區的開源項目，其源碼會一直停留在「孤芳自賞」階段。“我有一個想法，這是我的代碼”可能是最糟糕的貢獻方式，因為在沒有任何文檔的情況下 Committers 不得不通過代碼去嘗試理解貢獻者的意圖，這種反向推導往往會耗費 Committers 和貢獻者本人額外的時間精力，導致非常高的溝通成本和更久的代碼合併週期。另一方面，缺少嚴格的代碼審查機制和規範的 Pull Requst 流程會導致開源代碼的質量大幅降低，這就是為何小到發現 typo、簡單的 bugfix 都需要有一套完整的機制，而大到一個模塊的重構、feature 的新增更需要提供詳細的設計文檔、發起投票。這部分工作所佔的比重非常高，所以真正到寫代碼的階段是自然而然水到渠成的。而完善詳盡的文檔、及時準確的答疑、百花齊放的技術博客才能打造優質的社區生態，吸引更多的用戶參與使用，進而反哺社區。拿最近成為 Committer 的 Konstantin 和 Seth 來說，他們提名的主要貢獻就是文檔，這也可以看出 Flink PMC 委員會對於文檔貢獻的認可和重視，特別是貢獻中文文檔（翻譯）的門檻相對較低，只要有一定英語基礎 & 文字表達能力即可，屬於最適合初學者開始開源貢獻的起步選擇。Flink 社區目前正在招募翻譯者，下面也會詳細介紹翻譯的具體流程。
2. 準備工作
- 訂閱郵件列表
Flink 社區討論主要通過郵件完成，所以參與貢獻的第一步是加入到郵件列表獲取最新的討論信息。主要的郵件列表有用戶郵件列表（_[email protected] & [email protected]）和開發者郵件列表（[email protected]）。關於郵件列表的更多信息可以參考 https://flink.apache.org/community.html#mailing-lists_ 。發送郵件到相應的郵件列表並回復確認信息即可訂閱。
E.g. 想訂閱開發者郵件列表就發送無內容的郵件到 _[email protected]_，社區會回覆一封郵件詢問你是否確認加入，再回復一下確認就可以了。
Flink 社區每天來往的郵件非常多，有效整理歸檔可以幫忙自己快速定位相關 topic，雲邪在這裡分享了他的 Gmail 收件規則 _https://gist.github.com/wuchong/ad6a3bd241aca0e04eef93ae71fba73b_，可作為參考。
- 關注 JIRA 模塊
Flink 社區通過 JIRA 管理所有 Issue，所以在開始貢獻前我們需要有一個 JIRA 賬號。雖然 JIRA 不支持關注某個特定的模塊，但我們可以使用 JIRA Filters 來跟蹤自己感興趣的模塊。
操作步驟如下
- 切換到 JIRA Issues 頁，將搜索框從 Basic 切換到 Advanced 模式。
- 加入自己感興趣的 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 時使用的郵箱。
- 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 給自己（雲邪）。
Step2：開始工作 & 檢查待提交的內容。注意所有文檔都以 .md 為後綴，中文文檔名會有 zh 標識符，初始狀態下中文文檔裡的內容都是英文。我們切換到本地倉庫切換到 docs 目錄下找到要翻譯的文檔，就可以遵循翻譯規範開始工作了。
翻譯工作完成後，最好在本地進行渲染查看效果後再進行提交，方法如下：
切換到 docs 下的 docker 目錄啟動 docker 環境
cd ${your-local-dir}/flink/docs/docker./run.sh
緊接著編譯本地文檔，一般來說需要 1 ~ 2 min
./build docs.sh -p
然後打開 localhost:4000 切換到中文版就可以檢查渲染後的文檔，比如排版格式及頁面裡的超鏈接能否正常打開等等，確認無誤後就可以提交了。注意：要為指向其他文檔的超鏈接做中文適配。
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（改動是否需要新文檔）
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 的貢獻者名單。
如何成為優秀的 Contributor
提交第一個 PR 只是萬里長征的第一步，那如何成為優秀的 Contributor 乃至 Committer 呢？下面總結了三個 tips 或許可以幫到你。
1. 積極參與用戶答疑
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 的路上持續前進。
擴展閱讀：