咱們是如何管理一個 1w+ stars 的開源倉庫的

對於每一個開發者來說，git 倉庫是咱們幾乎天天都要接觸的東西，可是實際上大多數的 git 倉庫管理都是很是隨性且不規範的，在某些狀況下這樣作並無太大的問題，可是當協做成員逐漸增多、倉庫職責逐步擴展時，不少本來不規範的小問題會被逐漸放大乃至產生一些極爲嚴重的問題。筆者所在的飛冰（ICE）團隊在 2018 年 2 月開源了 alibaba/ice 這個倉庫，通過不到一年的時間終於在 2018 年底達到了 1w+ stars 的里程碑，在管理這個倉庫以及運營社區的過程當中咱們積累了一些或大或小的最佳實踐，但願能分享出來幫助到其餘開源或者沒開源的 git 倉庫管理者。注：對於 git 的操做，筆者自知還處於一個比較初級的階段，若有錯誤的地方還望指出。

合理的拆分倉庫

當咱們說管理倉庫的時候，其實面向的不是一個單一的倉庫，而是一個產品、一個項目甚至一個業務，這背後可能會有多個倉庫也可能只有一個倉庫，所以在前期的規劃上要儘可能梳理清楚，核心避免兩個誤區：

誤區 1：每一個職責都建一個倉庫

這個方案多是多數人的直覺反應，這種方式會讓產品對應的倉庫數快速增多，致使長期管理成本陡增：

• 倉庫權限管理成本高且容易混亂
• 代碼開發提交成本高
• issue/PR 太過零散，難以統計管理
• ……

實際上，飛冰（ICE）原先在內部的時候，咱們開發了不少業務組件，每一個業務組件都是一個單獨倉庫，而後最近在作統一升級（工具、規範或者其餘變動致使）的時候給筆者我的帶來很是大的困擾：

• 有的組件（倉庫）已經再也不維護但沒有任何標記
• group 權限管理太過鬆散致使出現一些跟官方無關的組件
• 升級過程當中須要頻繁切換倉庫操做

所以，咱們須要避免過於零散的管理方式，而後結合實際場景作適當的聚合。

誤區 2：全部的職責都用一個倉庫承載

在前端社區裏，隨着 lerna 這個批量發佈包工具的出現，這種方式愈來愈流行，一些很是熱門的項目好比 babel、React、jest 等都逐漸遷移到這個方案。先拋開 lerna 這個工具提供的能力，這種聚合式的管理方式給倉庫管理者節省了不少成本，好比：

• 只須要管理一個倉庫
• issue/PR/wiki 等都收斂到一個地方管理

可是在實踐這種方式的時候有可能會走偏，仍是以筆者所在的 ICE 團隊作反面教材，踩了誤區 1 的坑以後，在作開源版本的時候咱們過段把全部包都放到同一個倉庫，而後經過目錄結構來保證職責清晰，這個方式也一樣如上面所提到的給咱們的管理帶來了諸多便利，但在經歷了一年的迭代以後目前也遇到了一些問題：

• 職責多表明代碼多，而後隨着歷史記錄的增加，倉庫 clone 速度一日不如一日，尤爲在一些小公司的慢速網路環境下（即使加了 --depth）
• 目錄結構相對複雜，對有心貢獻代碼的社區同窗不夠友好

所以咱們推薦「在方案 2 的基礎上按照職責再作一層拆分」，結合 alibaba/ice 這個倉庫，咱們後續會把 React 物料代碼、Vue 物料代碼、Angular 物料代碼分別拆出去成爲三個獨立倉庫，一方面下降主倉庫的體積，另外一方面Vue 的貢獻者不須要關心其餘對他沒有意義的文件目錄。

創建團隊內的操做規範

筆者曾經有幸參與過淘寶前端團隊的代碼規範制定以及相關工具落地，所以深知規範之於團隊的重要性，同時也有一些制定規範的原則：(1) 規範首先保證正確，其次提高質量；(2) 規範不能過多影響到效率（二者的權衡須要結合實際場景）。如下就是咱們目前在遵循的一些規範：

保護分支

根據倉庫狀況設定保護分支，禁止直接往保護分支提交代碼，在很是特殊的狀況下 admin 帳戶能夠繞過。

新建分支規則

• 分支名稱須要有語義，好比 ice-scripts/fix-foo-bug
• 若是需求比較簡單，時間週期比較短，那麼直接從 master 切一個分支，而後經過 PR 合併後到 master，合併以後發佈對應包的版本
• 若是需求包含多個變動點，好比 Iceworks 發佈版本，每每涉及到多個功能點，開發週期通常會在一週左右，若是每一個 PR 都往 master 上合併，很難把控總體的進度。所以咱們有如下約定：
  1. 先從 master 切出 release 分支（如 release/iceworks-2.16.0），而後提一個基準 PR，PR 中須要補充當前版本包含的功能列表以及發佈前後順序等，該 PR 主要用於管理這次版本開發進度，代碼無需 review，release 分支不容許直接推送代碼
  2. 而後每一個功能變動都從 release 分支切出新分支，同時 PR 也須要合併到對應 release 分支，切出的分支不須要包含版本信息（好比 iceworks/fix-xxxx 便可）
  3. 等全部 PR Review 完成而且合併到 release 分支以後，在 release 分支進行發佈，發佈完成後再將 release -> master 的 PR 合併（此處不在 master 分支發佈的緣由是擔憂發佈時可能會出各類問題，須要再次作代碼變動）

commit message 規範

好的 commit message 可讓人快速瞭解代碼意圖，加速 review 進程，將來對於整個代碼倉庫的歷史追溯也會更加方便，關於這一點社區有足夠多的規範能夠參考，此處再也不一一贅述，有興趣能夠參考末尾的參考連接。

PR 合併流程

github 默認提供了三種合併 PR 的方式，關於三種方式的區別能夠參考文末的相關連接，咱們認爲大多數狀況應該選擇 Squash and merge，由於 squash 會將當前 PR 的多個 commit 合併，讓整個提交歷史更加乾淨清晰，可是在將上文提到的 release 分支合併到 master 時，是否應該將每一個功能點的 commit 合併成一個 release commit，目前咱們尚未思考清楚，但願能獲得一些建議或者指導。同時在合併 PR 的時候 Reviewer 有責任從新編寫 commit message 以保證語義更加準確。

這裏簡單追溯一點歷史：在最先期的時候，github 尚未提供 squash merge 的方式，當咱們向開源倉庫提交一個 PR 時，在倉庫做者 review 完成以後通常會要求提交者將 commit 合併，所以不少人都有谷歌過「如何合併 commit」這樣的關鍵詞，而現在只須要點一下按鈕便可，這也是工具對效率提高的一個體現。

發佈流程

對於管理工具包的同窗，都應該熟悉而且遵循 Semver 規範（語義化版本），這是原則，在此基礎上須要遵循如下規範：

• 測試版本：版本號須要遵循 x.y.z-n 的規則，經過 npm publish --tag beta 發佈，不少同窗包含筆者本人常常會忘記 --tag beta，不知道有沒有更加有效的方式約束？
• 正式版直接經過 npm publish 發佈，發佈以後執行 tnpm sync 同步內部版本
• 正式版本發佈以後，須要同時建立對應的 git tag，tag 命名規則：產品名/x.y.z，好比 ice-scripts/1.0.2

其餘不重要的事情

如何保證規範落地

結合曾經在淘寶前端團隊推進的規範落地以及當下在 ICE 團隊制定的規範，兩點結論可供參考：

• 規範須要保證多數人承認，而後由鬆到緊逐步迭代，人跟着規範逐步成長
• 小團隊靠素養，大團隊靠工具：在小團隊內製定規範，須要作的就是反覆強調，逐漸讓每一個人造成習慣；而在大團隊裏顯然是無法關注到每一個人的，此時須要藉助工具，好比 eslint，commit-check 以及像門神這種強流程的工具

如何迭代歷史版本

上文說的一些工具包的發版，假設我有一個工具包 ice-scripts 在 1.6.5 的基礎發佈了一個 break change 的版本 2.0.0，正常狀況下咱們確定是在 master 分支（2.0.0 的代碼）的基礎上逐步迭代，但 1.x 的版本可能還有用戶使用，當咱們須要修復 1.x 的一個 bug 時如何去作？這裏推薦一個流程：

• 首先基於 git tag ice-scripts/1.6.5 切出一個 stable/ice-scripts-1.x 的分支（幸好以前打了 tag，不然要找到對應的 commit 仍是有點工做量的）
• 將 stable/ice-scripts-1.x 設爲保護分支，能夠理解爲 1.x 版本的 master 分支
• 從 stable/ice-scripts-1.x 切出新分支 ice-scripts-1.x/fix-bar，而後修改代碼提交 PR 到 stable/ice-scripts-1.x 分支上
• Review 完成後合併代碼，而後在 stable/ice-scripts-1.x 分支上進行發佈

如何作好答疑

運營社區的過程必定須要頻繁面對用戶的疑問，如何在知足用戶的同時又能保證自身投入不影響到正常工具顯得極爲重要了，對於技術產品，根據面向用戶羣體的不一樣目前兩種主流答疑方式：

• github issue: 純異步交流，保證全部問題討論都能沉澱下來，同時由於異步溝通有成本，你們會努力一點表達清楚本身的意圖，相對來說溝通質量更高，但響應速度之類的沒法保證
• 類釘釘羣：同步交流，響應速度快，可是對於維護者來講時間容易被打碎，下降工做效率

答疑這塊目前總體上仍是佔用了太多時間，這塊也一直處於探索階段：

• 作好產品以及文檔的積累
• 釘釘羣答疑進行值班機制，每一個人負責一天，每一個人須要對產品的全貌正確瞭解更多：事實上會有點難
• 釘釘機器人問題沉澱
• 引入外包機制

如何管理 issue

ICE 目前總體的 issue 管理作的很差，筆者也是近期開始治理這塊，一些建議僅供參考：

• 經過 issue 模板努力提高 issue 質量：ICE 倉庫裏早期的 issue 質量很是低，不少問題都沒法復現
• 基於產品分類建議對應的標籤分類，每一個 issue 關聯標籤，而後由對應負責人統一處理
• issue 不要求及時處理，但鼓勵能經過溝通或其餘方式快速明確問題，防止時間長了不理解 issue 的描述而後又沒法跟 issue 做者溝通

如何運營社區

ICE 團隊目前維護着 5 個釘釘答疑羣（每一個 1000 人）以及技術論壇的官方賬號，但總體活躍度都比較通常，目前不管是精力上的投入仍是運營產品的經驗都比較缺失，但願能獲得一些建議或者支持。

有趣的機器人

github 上有不少方便的機器人（or App?），這裏推薦我的以爲比較有用的兩個機器人：

• delete-merged-branch：合併 PR 以後會自動刪除對應分支，防止無用分支的堆積
• Weekly Digest：每週建立一個 issue，彙總倉庫一週內的動態，好比：新增了哪些 issue/PR，有哪些人 star 了倉庫等，示例 Weekly Digest (30 December, 2018 - 6 January, 2019)

其餘有趣的機器人歡迎推薦。

相關連接

• alibaba/ice 官方倉庫
• 寫出好的 commit message
• 5.1 代碼合併：Merge、Rebase 的選擇
• Semver 規範