TiDB 開源社區指南（上）

做者：申礫

本系列文章旨在幫助社區開發者瞭解 TiDB 項目的全貌，更好的參與 TiDB 項目開發。大體會分兩個角度進行描述：

• 從社區參與者的角度描述如何更好的參與 TiDB 項目開發；
• 從 PingCAP 內部團隊的角度展現 TiDB 的開發流程，包括版本規劃、開發流程、Roadmap 制定等。

但願經過一內一外兩條線的描述，讀者能在技術以外對 TiDB 有更全面的瞭解。本篇將聚焦在社區參與者的角度進行描述，也就是「外線」。

瞭解 TiDB

參與一個開源項目第一步老是瞭解它，特別是對 TiDB 這樣一個大型的項目，瞭解的難度比較高，這裏列出一些相關資料，幫助 newcomers 從架構設計到工程實現細節都能有所瞭解：

• Overview
• How we build TiDB
• TiDB 源碼閱讀系列文章
• Deep Dive TiKV (Work-In-Process)

固然，最高效地熟悉 TiDB 的方式仍是使用它，在某些場景下遇到了問題或者是想要新的 feature，去跟蹤代碼，找到相關的代碼邏輯，在這個過程當中很容易對相關模塊有了解，很多 Contributor 就是這樣完成了第一次貢獻。 

咱們還有一系列的 Infra Meetup，大約兩週一次，若是方便到現場的同窗能夠聽到這些高質量的 Talk。除了北京以外，其餘的城市（上海、廣州、成都、杭州）也開始組織 Meetup，方便更多的同窗到現場來面基。

發現能夠參與的事情

對 TiDB 有基本的瞭解以後，就能夠選一個入手點。在 TiDB repo 中咱們給一些簡單的 issue 標記了 for-new-contributors 標籤，這些 issue 都是咱們評估過容易上手的事情，能夠以此爲切入點。另外咱們也會按期舉行一些活動，把框架搭好，教程寫好，新 Contributor 按照固定的模式便可完成某一特性開發。

固然除了那些標記爲 for-new-contributors 的 issue 以外，也能夠考慮其餘的 issue，標記爲 help-wanted 標籤的 issue 能夠優先考慮。除此以外的 issue 可能會比較難解決，須要對 TiDB 有較深刻的瞭解或者是對完成時間有較高的要求，不適合第一次參與的同窗。

固然除了現有的 issue 以外，也歡迎將本身發現的問題或者是想要的特性提爲新的 issue，而後自投自搶 :) 。 

當你已經對 TiDB 有了深刻的瞭解，那麼能夠嘗試從 Roadmap 上找到感興趣的事項，和咱們討論一下如何參與。

討論方案

找到一個感興趣的點以後，能夠在 issue 中進行討論，若是是一個小的 bug-fix 或者是小的功能點，能夠簡單討論以後開工。即便再簡單的問題，也建議先進行討論，以避免出現解決方案有問題或者是對問題的理解出了誤差，作了無用功。

可是若是要作的事情比較大，能夠先寫一個詳細的設計文檔，提交到 docs/design 目錄下面，這個目錄下有設計模板以及一些已有的設計方案供你參考。一篇好的設計方案要寫清楚如下幾點：

• 背景知識
• 解決什麼問題
• 方案詳細設計
• 對方案的解釋說明，證實正確性和可行性
• 和現有系統的兼容性
• 方案的具體實現 

用一句話來總結就是寫清楚「你作了什麼，爲何要作這個，怎麼作的，爲何要這樣作」。若是對本身的方案不太肯定，能夠先寫一個 Google Doc，share 給咱們簡單評估一下，再提交 PR。

提交 PR

按照方案完成代碼編寫後，就能夠提交 PR。固然若是開發還沒有完成，在某些狀況下也能夠先提交 PR，好比但願先讓社區看一下大體的解決方案，這個時候請將 PR 標記爲 WIP。

對於 PR 咱們有一些要求：

1. 須要能經過 make dev 的測試，跑過基本的單元測試；
2. 必須有測試，除非只是改動文檔或者是依賴包，其餘狀況須要有充足的理由說明沒有測試的緣由；
3. 代碼以及註釋的質量須要足夠高，這裏 有一些關於編碼風格和 commit message 的 guide；
4. 請儘量詳細的填寫 PR 的描述，並打上合適的 label。

對於 PR 的描述，咱們提供了一個模板，但願你們可以認真填寫，一個好的描述可以加速 PR 的 review 過程。經過這個模板可以向 reviewers 以及社區講明白：

• 這個PR 解決什麼問題：相關的問題描述或者是 issue 連接；
• 如何解決：具體的解決方法，reviewers 會根據這裏的描述去看代碼變更，因此請將這一段寫的儘量詳細且有幫助；
• 測試的狀況；
• 其餘相關信息（若是須要）：benchmark 結果、兼容性問題、是否須要更新文檔。

最後再說幾句測試，正確性是數據庫安身立命之本，怎麼強調測試都不爲過。PR 中的測試不但須要充足，覆蓋到所作的變更，還須要足夠清晰，經過代碼或者註釋來表達測試的目的，幫助 reviewer 以及從此可能變更/破壞相關邏輯的人可以容易的理解這段測試。一段完善且清晰的測試也有利於讓 reviewer 相信這個 Patch 是正確的。

PR review

PR review 的過程就是 reviewer 不斷地提出 comment，PR 做者持續解決 comment 的過程。

每一個 PR 在合併以前都須要至少獲得兩個 Committer/Maintainer 的 LGTM，一些重要的 PR 須要獲得三個，好比對於 DDL 模塊的修改，默認都須要獲得三個 LGTM。

Tips：

• 提了PR 以後，能夠 at 一下相關的同窗來 review；
• Address comment 以後能夠 at 一下以前提過 comment 的同窗，標準作法是 comment 一下 「PTAL @xxx」，這樣咱們內部的 Slack 中能夠獲得通知，相關的同窗會受到提醒，讓整個流程更緊湊高效。

與項目維護者之間的交流

目前標準的交流渠道是 GitHub issue，請你們優先使用這個渠道，咱們有專門的同窗來維護這個渠道，其餘渠道不能保證獲得研發同窗的及時回覆。這也是開源項目的標準作法。

不管是遇到 bug、討論具體某一功能如何作、提一些建議、產品使用中的疑惑，均可以來提 issue。在開發過程當中遇到了問題，也能夠在相關的 issue 中進行討論，包括方案的設計、具體實現過程當中遇到的問題等等。

最後請你們注意一點，除了 pingcap/docs-cn 這個 repo 以外，請你們使用英文。

更進一步

當你完成上面這些步驟的以後，恭喜你已經跨過第一個門檻，正式進入了 TiDB 開源社區，開始參與 TiDB 項目開發，成爲 TiDB Contributor。

若是想更進一步，深刻了解 TiDB 的內部機制，掌握一個分佈式數據庫的核心模塊，並能作出改進，那麼能夠了解更多的模塊，提更多的 PR，進一步向 Committer 發展（這裏 解釋了什麼是 Committer）。目前 TiDB 社區的 Committer 還很是少，咱們但願從此能出現更多的 Committer 甚至是 Maintainer。

從 Contributor 到 Committer 的門檻比較高，好比今年的新晉 Committer 杜川同窗，在成爲 Committer 的道路上給 tidb/tikv 項目提交了大約 80 個 PR，而且對一些模塊有很是深刻的瞭解。固然，成爲 Committer 以後，會有必定的權利，好比對一些 PR 點 LGTM 的權利，參加 PingCAP 內部的技術事項、開發規劃討論的權利，參加按期舉辦的 TechDay/DevCon 的權利。目前社區中還有幾位貢獻者正走在從 Contributor 到 Committer 的道路上。