码住！Flink Contributor 速成指南
簡(jiǎn)介：?不管初衷是什么，Flink 都非常歡迎大家一起建設(shè)和完善社區(qū)。在開(kāi)始具體的貢獻(xiàn)步驟之前，我們先簡(jiǎn)要介紹一下參與貢獻(xiàn)的幾種途徑，以及 Clarify 關(guān)于開(kāi)源貢獻(xiàn)的一些固有印象。
作者：伍翀（云邪），Apache Flink PMC，阿里巴巴技術(shù)專(zhuān)家
整理者：陳婧敏（清樾）
本文整理自 Apache Flink PMC 伍翀（云邪）直播分享，旨在為具備一定大數(shù)據(jù)基礎(chǔ)、對(duì) Flink 社區(qū)發(fā)展感興趣的同學(xué)提供參與貢獻(xiàn)的一些經(jīng)驗(yàn)和流程。
為什么要參與開(kāi)源社區(qū)
作為 Apache Flink PMC member 的云邪根據(jù)自身經(jīng)歷總結(jié)了參與開(kāi)源社區(qū)發(fā)展的三個(gè)主要原因。
1. 開(kāi)源精神
「自由」可謂是開(kāi)源精神的核心，自由意味著世界范圍內(nèi)無(wú)拘無(wú)束的交流分享與思維的碰撞。云邪自述“拿我個(gè)人來(lái)說(shuō)，我在大學(xué)階段正好經(jīng)歷了 Hadoop、Spark 大火的階段，那時(shí)候就特別憧憬做開(kāi)源，特別崇拜能熟讀源碼的大神，特別希望自己有一天也能夠?qū)懞芏嚅_(kāi)源代碼，讓自己寫(xiě)的代碼被上萬(wàn)的用戶(hù)使用。所以對(duì)于我來(lái)說(shuō)，參與開(kāi)源就像是一個(gè)愛(ài)好一樣，愿意為之付出時(shí)間和努力。我也很幸運(yùn)地在畢業(yè)后就接觸上了開(kāi)源社區(qū)。”
2. 技術(shù)成長(zhǎng)
參與開(kāi)源是提升個(gè)人代碼質(zhì)量的好方法。開(kāi)源社區(qū)對(duì)于代碼和設(shè)計(jì)要求非常高，不像一些內(nèi)部項(xiàng)目相對(duì)隨意。對(duì)于設(shè)計(jì)，Flink 社區(qū)有一套專(zhuān)門(mén)的 FLIP 機(jī)制，任何重大的貢獻(xiàn)都會(huì)經(jīng)過(guò)公開(kāi)和細(xì)致的討論。對(duì)于代碼，Flink CTO 親自寫(xiě)了 26 頁(yè)的 Code style 指南，此外每次提交 PR 后也會(huì)收到 Committers 的 Review 建議，所以持續(xù)地在開(kāi)源社區(qū)里貢獻(xiàn)代碼，對(duì)于個(gè)人的系統(tǒng)思維能力和代碼能力都有很大提升。
3. 職業(yè)規(guī)劃
如果你在準(zhǔn)備跳槽或是公司內(nèi)部晉升，除了現(xiàn)有的 Title 外，參與開(kāi)源社區(qū)的經(jīng)歷絕對(duì)是一個(gè)加分項(xiàng)，因?yàn)殚_(kāi)源產(chǎn)品本身就帶有網(wǎng)紅的標(biāo)簽，而參與其中則有助于提高自身的影響力 & 結(jié)識(shí)同行業(yè)的大牛們。開(kāi)源貢獻(xiàn)除了能直接地反映你的代碼能力外，成為 Committer 甚至 PMC member 更能證明你的熱情 & 毅力 & 溝通協(xié)作方面的 Soft skills（因?yàn)檫@需要你持續(xù)完成高質(zhì)量的貢獻(xiàn)，與社區(qū)其它成員共同協(xié)作，在有意見(jiàn)分歧的時(shí)候保持開(kāi)放友好的態(tài)度 _etc_.）。
如何成為 Contributor
1. 貢獻(xiàn)途徑
不管初衷是什么，Flink 都非常歡迎大家一起建設(shè)和完善社區(qū)。在開(kāi)始具體的貢獻(xiàn)步驟之前，我們先簡(jiǎn)要介紹一下參與貢獻(xiàn)的幾種途徑, 以及 Clarify 關(guān)于開(kāi)源貢獻(xiàn)的一些固有印象。
說(shuō)起開(kāi)源貢獻(xiàn)可能大家的直觀反應(yīng)就是貢獻(xiàn)代碼。不過(guò)在 Flink 社區(qū)中有非常多的參與貢獻(xiàn)的方式，包括文檔、翻譯、答疑、測(cè)試、以及代碼等，并且社區(qū)將文檔貢獻(xiàn)放在第一位，代碼貢獻(xiàn)放在最后。因?yàn)?Apache 社區(qū)對(duì)于代碼貢獻(xiàn)的態(tài)度是 ?Community Over Code，Flink CTO 更是親自發(fā)推說(shuō)明代碼貢獻(xiàn)的“不重要性”。
為什么呢？因?yàn)殚_(kāi)源項(xiàng)目的良性發(fā)展并不是簡(jiǎn)單地依靠狂懟代碼，沒(méi)有社區(qū)的開(kāi)源項(xiàng)目，其源碼會(huì)一直停留在「孤芳自賞」階段。“我有一個(gè)想法，這是我的代碼”可能是最糟糕的貢獻(xiàn)方式，因?yàn)樵跊](méi)有任何文檔的情況下 Committers 不得不通過(guò)代碼去嘗試?yán)斫庳暙I(xiàn)者的意圖，這種反向推導(dǎo)往往會(huì)耗費(fèi) Committers 和貢獻(xiàn)者本人額外的時(shí)間精力，導(dǎo)致非常高的溝通成本和更久的代碼合并周期。另一方面，缺少?lài)?yán)格的代碼審查機(jī)制和規(guī)范的 Pull Requst 流程會(huì)導(dǎo)致開(kāi)源代碼的質(zhì)量大幅降低，這就是為何小到發(fā)現(xiàn) typo、簡(jiǎn)單的 bugfix 都需要有一套完整的機(jī)制，而大到一個(gè)模塊的重構(gòu)、feature 的新增更需要提供詳細(xì)的設(shè)計(jì)文檔、發(fā)起投票。這部分工作所占的比重非常高，所以真正到寫(xiě)代碼的階段是自然而然水到渠成的。而完善詳盡的文檔、及時(shí)準(zhǔn)確的答疑、百花齊放的技術(shù)博客才能打造優(yōu)質(zhì)的社區(qū)生態(tài)，吸引更多的用戶(hù)參與使用，進(jìn)而反哺社區(qū)。拿最近成為 Committer 的 Konstantin 和 Seth 來(lái)說(shuō)，他們提名的主要貢獻(xiàn)就是文檔，這也可以看出 Flink PMC 委員會(huì)對(duì)于文檔貢獻(xiàn)的認(rèn)可和重視，特別是貢獻(xiàn)中文文檔（翻譯）的門(mén)檻相對(duì)較低，只要有一定英語(yǔ)基礎(chǔ) & 文字表達(dá)能力即可，屬于最適合初學(xué)者開(kāi)始開(kāi)源貢獻(xiàn)的起步選擇。Flink 社區(qū)目前正在招募翻譯者，下面也會(huì)詳細(xì)介紹翻譯的具體流程。
2. 準(zhǔn)備工作
- 訂閱郵件列表
Flink 社區(qū)討論主要通過(guò)郵件完成，所以參與貢獻(xiàn)的第一步是加入到郵件列表獲取最新的討論信息。主要的郵件列表有用戶(hù)郵件列表（_user@flink.apache.org?&?user-zh@flink.apache.org）和開(kāi)發(fā)者郵件列表（dev@flink.apache.org）。關(guān)于郵件列表的更多信息可以參考?https://flink.apache.org/community.html#mailing-lists_ 。發(fā)送郵件到相應(yīng)的郵件列表并回復(fù)確認(rèn)信息即可訂閱。
E.g.?想訂閱開(kāi)發(fā)者郵件列表就發(fā)送無(wú)內(nèi)容的郵件到 _dev-subscribe@flink.apache.org_，社區(qū)會(huì)回復(fù)一封郵件詢(xún)問(wèn)你是否確認(rèn)加入，再回復(fù)一下確認(rèn)就可以了。
Flink 社區(qū)每天來(lái)往的郵件非常多，有效整理歸檔可以幫忙自己快速定位相關(guān) topic，云邪在這里分享了他的 Gmail 收件規(guī)則 _https://gist.github.com/wuchong/ad6a3bd241aca0e04eef93ae71fba73b_，可作為參考。
- 關(guān)注 JIRA 模塊
Flink 社區(qū)通過(guò) JIRA 管理所有 Issue，所以在開(kāi)始貢獻(xiàn)前我們需要有一個(gè) JIRA 賬號(hào)。雖然 JIRA 不支持關(guān)注某個(gè)特定的模塊，但我們可以使用 JIRA Filters 來(lái)跟蹤自己感興趣的模塊。
操作步驟如下
- 目前 Flink 社區(qū)只有 Committer 才有權(quán)限將 Issue 指派給自己，所以如果是 Contributor 想解決它的話(huà)可以在 Issue 下方留言申請(qǐng)指派。一般情況下如果是簡(jiǎn)單的 typo 或 bugfix 時(shí) Committer 會(huì)直接指派，但如果涉及到比較復(fù)雜的改動(dòng)或是新的 feature 實(shí)現(xiàn)，在申請(qǐng)時(shí)就需要闡述清楚代碼層面的實(shí)現(xiàn)方案，與 Committer 達(dá)成一致后才會(huì)指派。另外可以點(diǎn)擊 Issue 頁(yè)面上的 Watchers 添加關(guān)注，后面這個(gè) Issue 的任何更新都會(huì)發(fā)送到注冊(cè) JIRA 時(shí)使用的郵箱。
- Fork Flink 倉(cāng)庫(kù) & 下載 Flink 源碼
首先你需要有一個(gè) GitHub 賬號(hào)，然后打開(kāi) Flink 的 GitHub 主頁(yè)?https://github.com/apache/flink?點(diǎn)擊?fork?按鈕，這樣就在自己的私人倉(cāng)庫(kù)下生成了一份鏡像。
然后在本地 clone Flink 倉(cāng)庫(kù)，用于同步 master 代碼>?git clone https://github.com/apache/flink.git ${your-local-dir}
接著添加自己 fork 的倉(cāng)庫(kù)用于提交開(kāi)發(fā)分支> >?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
開(kāi)始第一個(gè) Pull Request 之旅
對(duì)于參與社區(qū)的起步者，翻譯模塊通常是 “ROI” 最高的選擇。因?yàn)樗粌H易上手而且覆蓋了標(biāo)準(zhǔn)貢獻(xiàn)流程，分分鐘讓你變身 Apache Flink Contributor。下面我們將通過(guò)一個(gè)中文翻譯例子來(lái)展示完整的 Pull Request（以下簡(jiǎn)稱(chēng) PR） 流程。不過(guò)在起飛前，我們需要先了解翻譯規(guī)范，這里簡(jiǎn)要總結(jié)三點(diǎn)：
- 使用純文本工具進(jìn)行翻譯
- 漢字與英文、數(shù)字之間需要有空格
- 中文文檔鏈接需要在相應(yīng)英文文檔的?baseUrl?后添加?zh?適配
在上述準(zhǔn)備工作完成后，我們就進(jìn)入激動(dòng)人心的實(shí)戰(zhàn)階段了。
Step1：申請(qǐng)成為某個(gè) JIRA Issue 的 Assignee。由于這里是演示任務(wù)，所以我們打開(kāi)事先準(zhǔn)備好的翻譯任務(wù)?FLINK-17939 Translate "Python Table API Installation" page into Chinese，將它 assign 給自己（云邪）。
Step2：開(kāi)始工作 & 檢查待提交的內(nèi)容。注意所有文檔都以?.md?為后綴，中文文檔名會(huì)有?zh?標(biāo)識(shí)符，初始狀態(tài)下中文文檔里的內(nèi)容都是英文。我們切換到本地倉(cāng)庫(kù)切換到 docs 目錄下找到要翻譯的文檔，就可以遵循翻譯規(guī)范開(kāi)始工作了。
翻譯工作完成后，最好在本地進(jìn)行渲染查看效果后再進(jìn)行提交，方法如下：
切換到 docs 下的 docker 目錄啟動(dòng) docker 環(huán)境
cd ${your-local-dir}/flink/docs/docker
./run.sh
緊接著編譯本地文檔，一般來(lái)說(shuō)需要 1 ~ 2 min
./build docs.sh -p
然后打開(kāi)?localhost:4000?切換到中文版就可以檢查渲染后的文檔，比如排版格式及頁(yè)面里的超鏈接能否正常打開(kāi)等等，確認(rèn)無(wú)誤后就可以提交了。注意：要為指向其他文檔的超鏈接做中文適配。
Step3：提交階段準(zhǔn)備。最佳實(shí)踐是創(chuàng)建一個(gè)用于提交的分支，將改動(dòng)提交到這個(gè)分支上。比如這里創(chuàng)建一個(gè)叫?installation-translate?的分支并切換過(guò)去。
git checkout -b installation-translate
Flink 社區(qū)對(duì) Commit Message 的格式有一定要求，一般是
[${jira-issue-id}][${affected-component}] ${jira-issue-title}。
以 Demo 為例，就是?[FLINK-17939][docs-zh] Translate "Python Table API Installation" page into Chinese
在本地提交后就可以通過(guò)下面的命令把改動(dòng)推送到自己 fork 的遠(yuǎn)程私有倉(cāng)庫(kù)。
git push my installation-translate
Step4：準(zhǔn)備 PR。在將變更推送到自己 fork 的遠(yuǎn)程倉(cāng)庫(kù)后，Github 會(huì)自動(dòng)創(chuàng)建一個(gè)新的 PR 并返回 PR 頁(yè)面鏈接?[https://github.com/apache/flink/pull/12343](https://github.com/apache/flink/pull/12343)，在此基礎(chǔ)上需要填寫(xiě)如下信息，從而方便 reviewer 快速了解待 review 的 PR，提高合并效率。
- What is the purpose of the change（PR 目的）
- 一般來(lái)說(shuō)可以使用 JIRA Issue description 來(lái)描述
- Brief change log（PR 涉及到的 Commits 做了哪些改動(dòng)）
這個(gè)按需填寫(xiě)即可。比如翻譯任務(wù)就可以寫(xiě) translateflink/docs/dve/table/python/installation.zh.md。如果是較復(fù)雜的改動(dòng)，涉及到多個(gè)提交的話(huà)，最好按提交順序說(shuō)明簡(jiǎn)要總結(jié)每個(gè)提交的內(nèi)容并附上 Commit log 鏈接。
后面三個(gè)是選擇題，按需勾選即可：
- Verifying this change（確認(rèn)改動(dòng)了哪些內(nèi)容）
- Does this pull request potentially affect one of the following parts（確認(rèn)改動(dòng)的影響范圍）
- Documentation（改動(dòng)是否需要新文檔）
Step5：等待 Committer review。此時(shí)刷新 JIRA 頁(yè)通常可以看到 Issue Links 上的 PR 更新。一般來(lái)說(shuō)將 JIRA issue 指派給我們的 Committer 都會(huì)定期去 check 是否有他關(guān)注模塊的 PR，偶爾會(huì)遇到 Committer 很忙的情況時(shí)也可以在 PR 里 @ 某個(gè) Committer 來(lái)幫忙 review 自己的提交。通常 Committer 都會(huì)給出一些意見(jiàn)，提交者做出回復(fù)，有時(shí)可能還需要做出修改 & 再次提交。需要注意的是 Flink 社區(qū)不建議使用?git squash?將多次提交進(jìn)行合并壓縮，因?yàn)檫@會(huì)丟失掉歷史改動(dòng)記錄，建議修改后直接 append 到原來(lái)的 Commits 上即可。有時(shí)這一步可能會(huì)反復(fù)多次 & 會(huì)有多個(gè) Committers 參與，直到提交者和 Committers 達(dá)成一致。對(duì)于 Contributor 來(lái)說(shuō)整個(gè) PR 到這一步就結(jié)束了，后續(xù) Committer 會(huì)將其合并到 master 分支并關(guān)閉 PR。
簡(jiǎn)要總結(jié)一下，對(duì)于 contributor 來(lái)說(shuō)完整提交 PR 的步驟如下所示。
Step1：在 JIRA 上認(rèn)領(lǐng)感興趣的 Issue，請(qǐng) Committer 指派給自己。
Step2：完成 Issue 任務(wù)，做提交前的檢查。
Step3：按規(guī)范填寫(xiě) Commit 信息，并提交到遠(yuǎn)程私人倉(cāng)庫(kù)。
Step4：按規(guī)范填寫(xiě) PR 信息，等待 Committer review。
Step5：處理 Committers 的意見(jiàn)，有時(shí)包括修改代碼，重復(fù)此步驟直到 Committers 一致認(rèn)為改動(dòng)沒(méi)有問(wèn)題。
恭喜你已經(jīng)成為了 Flink Contributor！Flink 每個(gè)版本的 Release Announcement 都會(huì)有一項(xiàng) List of Contributors 列出所有貢獻(xiàn)者的名單，同時(shí) GitHub 貢獻(xiàn)者頁(yè)面上會(huì)列出歷史累計(jì) top 100 的貢獻(xiàn)者名單。
如何成為優(yōu)秀的 Contributor
提交第一個(gè) PR 只是萬(wàn)里長(zhǎng)征的第一步，那如何成為優(yōu)秀的 Contributor 乃至 Committer 呢？下面總結(jié)了三個(gè) tips 或許可以幫到你。
1. 積極參與用戶(hù)答疑
Flink 社區(qū)非常鼓勵(lì)能有更多的人參與到用戶(hù)郵件列表中來(lái)，2019 年 Apache 財(cái)報(bào)顯示 Flink 社區(qū)的郵件列表活躍度位列第一。社區(qū)每月都會(huì)統(tǒng)計(jì)各個(gè)郵件列表中積極回答問(wèn)題的貢獻(xiàn)者，會(huì)從這些活躍的貢獻(xiàn)者中尋找潛在的 Committer 候選人。
2. 代碼質(zhì)量贏得社區(qū)信任
對(duì)于代碼貢獻(xiàn)者，最佳實(shí)踐是：
- 遵循?Code style 規(guī)范，在 IDEA 配置?checkstyle.xml?隨時(shí)檢查，避免 PR 中出現(xiàn) style 不規(guī)范等低級(jí)問(wèn)題。
- 認(rèn)真填寫(xiě) PR 描述模板，尤其是“Brief change log” 部分，可參考?https://github.com/apache/flink/pull/7264和?https://github.com/apache/flink/pull/10013
- 任何新增功能都要有測(cè)試覆蓋，傾向于單元測(cè)試，而不是集成測(cè)試。
- 任何新增功能都要同步覆蓋文檔，中英文文檔都需要更新或建立 Issue。
- 關(guān)注 Azure 實(shí)驗(yàn)室的測(cè)試結(jié)果。
3. 具有社區(qū)意識(shí)
最后一點(diǎn)，Contributor 或者 Committer 的頭銜除了給我們個(gè)人帶來(lái)“職業(yè)光環(huán)”外，更重要的是帶來(lái)一份責(zé)任感，發(fā)自?xún)?nèi)心地幫助社區(qū)變得更好。比如不挑活、幫助新人成為貢獻(xiàn)者、幫助 review 新增 PR（Review指南）等等。
最后，借用「小王子」里的經(jīng)典臺(tái)詞 “It is the time you wasted on your rose that makes your rose important.” 祝大家在成為優(yōu)秀 Contributor 的路上持續(xù)前進(jìn)。
?
原文鏈接
本文為阿里云原創(chuàng)內(nèi)容，未經(jīng)允許不得轉(zhuǎn)載。
總結(jié)
以上是生活随笔為你收集整理的码住！Flink Contributor 速成指南的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問(wèn)題。
- 上一篇： Java编程技巧之单元测试用例编写流程
- 下一篇： 中台，很多人理解的都不对