因為業務需求，有讚自己造了很多輪子，元件庫尤其多，React，Vue，小程式都有涉及，其他開源專案有 zan-proxy 代理，PHP 的框架 zanphp 等。有人可能會覺得奇怪，為什麼有贊要造這麼多輪子？其實原因真的很簡單，就是因為現有的替代品無法滿足我們自身業務的需求，可能是不滿足我們的定製需求，也可能是功能不符合我們要求。根據業務需要，我們總結了一套適合自己的套路、規範，並把這些套路、規範做成了工具、元件庫或者框架。
這大概便是有贊內部啟動這些專案的緣由了。後來，隨著這些專案的逐步完善，一個自然而然的想法就是把它們開源了，也許別人也有類似我們的需求。
慢慢的，有讚的 Github 上就有了好多開源專案。在維護這些開源專案的過程中我們總結了一些經驗教訓，在此跟大家分享。
一、有讚的 Github 使用姿勢
Github 有一定的社交屬性，維護好一個開源專案除了程式碼寫得好，有一些使用姿勢也是很重要的，我們總結了幾點跟大家分享。
1. 一個好的 README 很重要
README 檔案是專案給人的第一印象，所謂人靠衣裝馬靠鞍，開源專案有個好的臉面是很重要的，尤其是當這個專案還是一個前端專案的時候。針對 README 檔案我們給出以下幾點建議：
- 同一個組織的 README 統一格式
- 最好有個英文版的 README
- 加上開發指南的連結
統一 README 格式的好處是讓別人一眼就認出這個專案是某某公司或者某某人的，有贊內部就維護了一份 README 的規範。模版內容很簡單，但是它保證了我們的專案有一定的識別度。
英文版的 README 不是為了裝逼，如果你篤定自己的使用者都在國內，那就只需要中文版的 README 就可以了。但是大部分情況下，專案維護者都希望自己的程式碼能夠幫助到更多人，包括國外的使用者，這時候英文 README 的價值就體現出來了。
開發指南很容易被忽略，它存在的目是幫助那些希望加入專案開發的開發者們快速上手。作為參與開源專案的開發者，他們對開發指南有哪些期望？我覺得無外乎幾點：
- 如何搭建開發環境？
- 有哪些未解決的問題需要幫助？
- 如何提交程式碼？
如果開發指南能夠回答這幾個問題，有經驗的開發者就可以比較快的參與進來。
2. 善用 Github 的 Issue 和 PR 模版
相信很多人都遇到過這樣一個尷尬的事情：有人在 Github 上提了一個 Issue，但是你看不懂這個 Issue 的描述，也不知道如何重現這個 Issue。
Github 提供了一個機制讓專案維護者能夠預先寫好 Issue 或者 PR 的模版，其他人過來提 Issue 或者 PR 的時候就可以在這個模版上修改。模版裡可以有針對性的告訴提 Issue 的人需要填寫那些資訊，這樣子大部分時候都可以避免上面提到的尷尬場面。
建立這些模版也很簡單，常見的方式是在倉庫的 .github 隱藏目錄下建立對應的模版 Markdown 檔案。最近 Github 剛剛更新了模版機制，允許同時建立多個 Issue / PR 的模版。
例如 babel 倉庫的 Issue 模版就有多個模版，每個模版對應不同的 Issue 型別，具體配置文件可以看這裡。
3. Labels
Github 的 Labels 功能主要是用來給 Issue / PR 做分類的，方便索引和搜尋。這裡主要想說的一點是 Github 預設建好的 Labels 其實並不好用，我們推薦將 Label 分成幾個正交的唯獨，每個維度對應幾個不同的 Label，可以參看這篇文章。
很多新手容易忽略 Label 這個功能，配合適當的 Label 分類，每個 Issue 都可以有一個很直觀的狀態展示。
4. 持續整合系統
Github 和 CI 系統的整合非常緊密，個人覺得體驗做的很好。CI 系統可以用來做一些單元測試，程式碼風格檢查等。很多倉庫裡 README 檔案上的程式碼覆蓋率資料都是在 CI 系統中生成提交的。
CI 除了用來執行單側，還可以用來做其他必要的程式碼檢查。例如 Zent 倉庫中有一個指令碼會在 CI 上檢查提交的程式碼有沒有按規範書寫，如果發現程式碼格式不對，那麼很有可能開發者沒有在本地安裝我們的 git 鉤子，這時我們會提示開發者在本地安裝鉤子，格式化程式碼然後重新提交。
#!/bin/bash
# Ensure everyone installs the git hook.
# The result is a guess, but false positive
# is not an issue here.
RED='\033[0;31m'
basepath=$(dirname $0)
fail () {
printf "${RED}$@\nAborting\n"
exit -1
}
pushd $basepath/.. >/dev/null 2>&1
yarn prettify
git diff-index --quiet HEAD --
rv=$?
popd >/dev/null 2>&1
if [ $rv -ne 0 ]; then
git diff-index HEAD --
fail 'Git hooks not installed. Follow these instructions on your local machine:\n1. yarn install\n2. yarn prettify\n3. Commit your changes and push.'
fi
複製程式碼這裡順帶說一下 Github 上常用的兩個 CI 系統使用感受：
- Travis 服務穩定性比較好，而且 Travis PR 的 build 是執行在源分支和當前 PR 分支的 merge 結果上的
- CircleCI 效能較好，但是穩定性相對較差，偶爾會抽風
Github 最近又上了一個新功能 Checks API，這個功能可以看成是原來 PR 和 CI 整合的一個升級版本，可以看見更加詳細的測試以及 Lint 報告。
5. 專案進度把控
GitHub 有兩個專案管理的工具，Milestone 和 Project。Project 可以顯示一個類似看板的功能，而 Milestone 的定位更加輕量，類似一個任務集合的 deadline 管理工具。對大部分開源專案而言，可能 Milestone 更加合適。
二、技巧分享
上面介紹了一些 Github 的使用技巧，這裡再分享一些專案開發、釋出以及維護過程的一些小技巧。一個開源專案決不僅僅是一串程式碼而已，它更是一個技術產品，這就要求我們以產品的要求來看待這個問題。
1. 版本釋出遵循生態系統的規範
以前端為例，NPM 的生態中絕大部分包都是使用 Semantic Versioning 的，如果我們專案的包不按照這個規則做，那麼很容易給使用者一個 “surprise”。對於版本號不必恐懼它的數字越來越大，它僅僅是一個數字而已。
2. 程式碼規範
相信只要是個成熟的專案肯定都有自己的編碼規範，有些專案可能提供了文件，告訴程式碼貢獻者應該如何編碼，同時也會有相應的 review，確保程式碼是符合規範的。但是，如果僅僅是程式碼樣式方面的規範，我們建議通過工具來確保規範的落地。我們不提供編碼規範的文件，但是我們有指令碼來格式化所有提交過來的程式碼。效果就是程式碼隨你怎麼寫，但是最終提交到 master 分支上都肯定都是按相同的規範書寫的。
這類格式化工具有很多，例如前端領域用的比較多的 Prettier，Go 語言自帶的 gofmt，以及 Reason 的 refmt 等。花點時間 Google 一下，找一個適合你專案的格式化工具。
3. Squash Merging
Github 針對 PR 提供了三種 merge 選項，這裡推薦只開啟 squash merge 這一種。所謂 squash merge 是指將 PR 分支上所有提交合併成一個新的 commit，然後將這個 commit 通過 fast-forward 的方式合併到目標分支，我們認為這種方式是最適合走 PR 的專案的。當然，如果你希望保留 PR 上的每一個提交記錄，那麼建議使用 rebase 的方式，不管是通過 Github 操作還是自己本地 rebase 後再提交。
4. 更新日誌
為了減少每次釋出的工作量，我們以前的更新日誌是指令碼根據 Github 的 Issue 以及 PR 記錄自動生成的。但是我們慢慢發現由於 Isssue 以及 PR 的標題規範性不是那麼好，導致更新日誌的可讀性變得比較差。另外一個問題是機器生成的更新日誌它沒法做到把同一元件的修改歸類整理到一起，這也是可讀性較差的一個原因。
我們現在的更新日誌是通過指令碼先生成一份“草稿”，然後由包的釋出者在這個基礎上總結提煉出一份方便閱讀的更新日誌。這種方式增加了一些釋出者的工作量，但是更新日誌的可讀性有較大提升，投入產出比還是可以接受的。
5. 技術產品的售後服務
“售後服務”是做開源專案的時候最容易被忽視的一點，如果我們以技術產品的要求去維護一個開源專案，那麼我們就有責任給使用者提供必要的支援。這些支援包括：完善的產品文件，答疑的群組以及一些產品技術部落格。有了這些“售後服務”我們才能形成一個完整的技術產品閉環，通過使用者的反饋不斷完善。
三、總結
本文從 Github 的使用姿勢切入，在專案開發、釋出、維護以及文件生成等方面分享了一些我們認為正確的開源專案維護心得。我們始終保持開放的心態，歡迎各位給我們提建議，一起改進開源專案的管理方式。
附錄
一些可能有用的工具連結：
- lerna: 大倉庫（Mono Repository）管理工具
- github-changelog-generator: Change log 自動生成工具
- conventional-changelog: 另一個 Change log 生成工具
- git-labelmaker: 自動建立 Github Labels
