如何貢獻(xiàn)復(fù)雜的項(xiàng)目
Iteration 12 [1]?從 4/23 開(kāi)始到 5/6 結(jié)束，為期兩周。這個(gè)周期成功走出了自己的舒適圈，探索了不少之前自己從未了解的東西，比如 tree-sitter，parser，hdfs，java 等等，感覺(jué)收獲非常多。最近反復(fù)讀了很多遍?@mitchellh [2] 寫(xiě)的?Contributing to Complex Projects [3]，今天這份周報(bào)就結(jié)合自己從零開(kāi)始參與貢獻(xiàn)?difftastic [4]?的經(jīng)歷來(lái)介紹如何貢獻(xiàn)復(fù)雜的項(xiàng)目。
前言
Contributing to Complex Projects 文章中將貢獻(xiàn)復(fù)雜項(xiàng)目分解為如下幾步：
Step 1: Become a User，成為用戶(hù)
Step 2: Build the Project，構(gòu)建項(xiàng)目
Step 3: Learn the Hot-Path Internals，學(xué)習(xí)內(nèi)部的關(guān)鍵邏輯
Step 4: Read and Reimplement Recent Commits，閱讀并重新實(shí)現(xiàn)最近的 commits
Step 5: Make a Bite-sized Change，做一個(gè)小變更
這些步驟適用于絕大多數(shù)項(xiàng)目，不過(guò)需要根據(jù)個(gè)人的偏好和實(shí)際情況做一些調(diào)整。比如我更傾向于做一些能最終合并到主干的事情，所以我參與貢獻(xiàn)的過(guò)程中往往會(huì)略過(guò)這里的 Step 4 并直接嘗試實(shí)現(xiàn)一些相對(duì)容易的 feature。大家在參與貢獻(xiàn)的過(guò)程也需要視情況調(diào)整自己的策略，不要教條式地照搬這里的步驟。
關(guān)于 difftastic
difftastic?[5] 是一個(gè)使用 Rust 開(kāi)發(fā)的能理解語(yǔ)義的 diff 工具。
它能夠理解我們?cè)诖a中修改的字符是數(shù)組的 Item 還是函數(shù)的參數(shù)，以 Javascripts 為例：
??高亮了?{,?}?但是這里的?foo();?并沒(méi)有修改，盡管 indent 變了，因?yàn)樗斫馇短?br>??將左邊的 bar()?和右邊的 bar(1)?對(duì)齊，因?yàn)樗浪麄兪峭粋€(gè) function call。
??這里的 eric 被移動(dòng)到了下一行，但是并沒(méi)有被高亮出來(lái)，因?yàn)樗肋@是一個(gè)不改變語(yǔ)義的換行。
在背后，difftastic 使用 tree-sitter^?[6] 來(lái)解析并對(duì)比文件的 AST，而不是基于純字符的差異對(duì)比。
目前 difftastic 支持 30 多種編程語(yǔ)言和配置文件的 diff，并能夠運(yùn)行在 Linux，MacOS，Windows 等主流平臺(tái)上。
成為用戶(hù)
開(kāi)源項(xiàng)目非常有趣的一點(diǎn)就在于：開(kāi)發(fā)者往往是用戶(hù)本身。Arch 之道中的 User centrality 原則指出：
許多 Linux 發(fā)行版都試圖變得更“用戶(hù)友好”，Arch Linux 則一直是，永遠(yuǎn)會(huì)是“以用戶(hù)為中心”。此發(fā)行版是為了滿(mǎn)足貢獻(xiàn)者的需求，而不是為了吸引盡可能多的用戶(hù)。Arch 適用于樂(lè)于自己動(dòng)手的用戶(hù)，他們?cè)敢饣〞r(shí)間閱讀文檔，解決自己的問(wèn)題。
我認(rèn)為這才是參與開(kāi)源最重要的一步。成為用戶(hù)，去使用它，去理解它是做什么的，去主動(dòng)發(fā)現(xiàn)不足和改進(jìn)點(diǎn)，而不是一上來(lái)就抱著長(zhǎng)長(zhǎng)的設(shè)計(jì)文檔啃。很多同學(xué)的開(kāi)源熱情往往就消磨在漫長(zhǎng)的文檔閱讀過(guò)程中：我們并不需要成為這個(gè)方面的專(zhuān)家才能參與項(xiàng)目的貢獻(xiàn)。在貢獻(xiàn) difftastic 之前，我對(duì) parser，tree-sitter 一無(wú)所知。即使是現(xiàn)在，我也對(duì)他們的了解也只局限于他們是做什么的，并不知道他們究竟如何工作，更別提閱讀他們的代碼了。但是這并不妨礙我為 difftastic 貢獻(xiàn)了多種語(yǔ)言的支持，并修復(fù)若干個(gè)引起 Crash 的 BUG。絕大多數(shù)開(kāi)源項(xiàng)目都會(huì)提供安裝和使用的文檔，difftastic 也不例外。我參考?Installation [7]?和?Usage [8]?中成功安裝并配置好了 difftastic。我很快發(fā)現(xiàn) difftastic 缺少對(duì) perl 和 hcl 的支持，于是決定為它加上。
構(gòu)建項(xiàng)目
參與開(kāi)源項(xiàng)目的第二步是部署開(kāi)發(fā)環(huán)境并進(jìn)行成功的構(gòu)建。difftastic 是一個(gè)純 Rust 的項(xiàng)目，相關(guān)的依賴(lài)比較少，使用 cargo build 即可編譯。
而復(fù)雜的項(xiàng)目往往會(huì)有著復(fù)雜的依賴(lài)，有些是項(xiàng)目必須的依賴(lài)，包括語(yǔ)言的構(gòu)建工具，依賴(lài)管理，編譯時(shí)工具等等，有些是項(xiàng)目開(kāi)發(fā)過(guò)程中需要用到的工具，比如靜態(tài)檢查，代碼格式化，集成測(cè)試等等。維護(hù)質(zhì)量比較好的項(xiàng)目往往會(huì)提供 Contributing 或者 Get Started 文檔來(lái)告知我們?nèi)绾螛?gòu)建項(xiàng)目，比如 TiDB 在?TiDB Development Guide: Get Started [9] 中詳細(xì)介紹了編譯 TiDB 需要依賴(lài)和步驟。更進(jìn)一步的，有的項(xiàng)目會(huì)提供一個(gè)一鍵式腳本（盡管我并不喜歡這種）來(lái)處理依賴(lài)問(wèn)題，比如 Databend 提供了?dev_setup.sh。[10] 像?Rust [11] 這樣開(kāi)發(fā)環(huán)境配置高度復(fù)雜的項(xiàng)目還會(huì)開(kāi)發(fā)額外的工具?[12] 來(lái)自動(dòng)化這些步驟。
作為開(kāi)發(fā)者，我們需要做到的事情是完整的閱讀 README 并尋找類(lèi)似的信息。如果沒(méi)找到的話(huà)可以嘗試約定俗成的方式，比如項(xiàng)目下有 Makefile，package.json，Cargo.toml，go.mod 這些標(biāo)志性的文件，我們可以直接嘗試使用對(duì)應(yīng)的命令。在成功構(gòu)建后，我們可以嘗試為項(xiàng)目提交一個(gè)修改 README 并增加構(gòu)建步驟的文檔以方便后來(lái)的同學(xué)。
學(xué)習(xí)關(guān)鍵路徑
學(xué)習(xí)關(guān)鍵路徑參與開(kāi)源項(xiàng)目的第三步是學(xué)習(xí)關(guān)鍵路徑。@mitchellh 將自己的方法概括為：trace down, learn up.：當(dāng)學(xué)習(xí)某個(gè)特性時(shí)：
首先自頂向下的尋找涉及到這個(gè)特性的 codepath 并忽略與之無(wú)關(guān)的細(xì)節(jié)
然后自底向上的學(xué)習(xí)這個(gè)子系統(tǒng)是如何工作的
嘗試去修改代碼，增加新的 log，增加簡(jiǎn)單的邏輯，修改某處細(xì)節(jié)，去理解為什么不工作了
閱讀與這個(gè)特性有關(guān)的文檔或者分享
不難發(fā)現(xiàn)，我們?nèi)粘５膶W(xué)習(xí)和工作中往往也是如此，只是我們需要系統(tǒng)的運(yùn)用到開(kāi)源項(xiàng)目中。項(xiàng)目中的代碼分布往往也遵循二八定律：20% 的代碼實(shí)現(xiàn)了 80% 的功能，所以我們沒(méi)有必要嘗試?yán)斫忭?xiàng)目中每一行代碼的細(xì)節(jié)。最好的方式是帶著問(wèn)題來(lái)閱讀代碼，只尋找跟自己實(shí)現(xiàn)功能有關(guān)的邏輯。維護(hù)良好的開(kāi)源項(xiàng)目往往會(huì)為核心的邏輯和模塊添加細(xì)致的文檔來(lái)解決常見(jiàn)的疑問(wèn)，很多時(shí)候看文檔就能解決我們的問(wèn)題。
difftastic 就是如此，作者非常棒地提供了?Adding A Parser [13] 的文檔。在文檔的幫助下，我只需要按照步驟依次執(zhí)行并解決簡(jiǎn)單的編譯問(wèn)題即可。當(dāng)然，更多的時(shí)候我們會(huì)面臨文檔的缺失和不足，這時(shí)候我們?cè)诶斫膺@一模塊后為項(xiàng)目貢獻(xiàn)這份文檔。就算理解錯(cuò)誤也沒(méi)有關(guān)系，在提交 PR 時(shí)我們可以跟作者進(jìn)行討論和確認(rèn)，一方面能夠幫助到有相同問(wèn)題的貢獻(xiàn)者，另一方面也能加深自己的理解和認(rèn)識(shí)。
從小變更做起
參與開(kāi)源的第四步是從小變更做起。貢獻(xiàn)文檔就是很好的開(kāi)始，這能夠幫助我們理解這個(gè)項(xiàng)目是如何進(jìn)行討論和開(kāi)發(fā)的。
請(qǐng)盡量避免上來(lái)就承擔(dān)特別復(fù)雜的任務(wù)，一方面我們需要通過(guò)貢獻(xiàn)來(lái)積累自己在社區(qū)的聲譽(yù)，另一方面復(fù)雜任務(wù)中途夭折會(huì)極大地打擊自己的信心。比較推薦的方式是從比較小的功能做起，最好能夠把影響局限在當(dāng)前的子系統(tǒng)。伴隨著我們實(shí)現(xiàn)功能，我們就能夠從當(dāng)前模塊出發(fā)，去理解更多的模塊如何共同工作。隨著了解的模塊增多，我們能夠發(fā)現(xiàn)更多可以改進(jìn)的點(diǎn)，參與到項(xiàng)目的持續(xù)演進(jìn)中去。
在?fix: Remove trailing lines before calculating max_lines [14] 中，我通過(guò)增加一些簡(jiǎn)單的 println 發(fā)現(xiàn)了問(wèn)題的根源在 LineNumber 計(jì)算有誤，從而給出了一個(gè) fix：
但是很快我發(fā)現(xiàn)這行代碼有些難以理解，所以我進(jìn)行了簡(jiǎn)單的重構(gòu)：
上述的變更都沒(méi)有修改到別的模塊，因此我只需要增加一個(gè)獨(dú)立的單元測(cè)試即可，而作者能夠快速的驗(yàn)證我的思路是否正確，避免了在 PR 中進(jìn)行來(lái)回的討論拉鋸。
總結(jié)
貢獻(xiàn)復(fù)雜的開(kāi)源項(xiàng)目并不困難，掌握正確的方法論，我們都能夠加入到開(kāi)源的行列中來(lái)：
成為用戶(hù)
構(gòu)建項(xiàng)目
學(xué)習(xí)關(guān)鍵路徑
從小變更做起
歡迎加入開(kāi)源社區(qū)～
參考鏈接
https://github.com/users/Xuanwo/projects/2/views/1?filterQuery=iteration%3A%22Iteration+12%22
https://github.com/mitchellh
https://mitchellh.com/writing/contributing-to-complex-projects
https://github.com/Wilfred/difftastic
https://github.com/Wilfred/difftastic
https://tree-sitter.github.io/tree-sitter/
https://difftastic.wilfred.me.uk/installation.html
https://difftastic.wilfred.me.uk/usage.html
https://pingcap.github.io/tidb-dev-guide/get-started/introduction.html
https://github.com/datafuselabs/databend/blob/fbd97e10a10d07815909722b78ebcd9c9975781d/scripts/setup/dev_setup.sh
https://github.com/rust-lang/rust
https://github.com/rust-lang/rust/blob/8a2fe75d0e6e024aa434e5b9c40adb2567f362b8/x.py
https://difftastic.wilfred.me.uk/adding_a_parser.html
https://github.com/Wilfred/difftastic/pull/261*
關(guān)于 Databend
Databend 是一款開(kāi)源、彈性、低成本，基于對(duì)象存儲(chǔ)也可以做實(shí)時(shí)分析的新式數(shù)倉(cāng)。期待您的關(guān)注，一起探索云原生數(shù)倉(cāng)解決方案，打造新一代開(kāi)源 Data Cloud。
Databend 文檔：https://databend.rs/
twitter：https://twitter.com/Datafuse_Labs
Slack：https://datafusecloud.slack.com/
Wechat：Databend
GitHub ：https://github.com/datafuselabs/databend
