有贊開源項目最佳實踐

時間 2019-12-06

標籤開源項目最佳實踐简体版

原文原文鏈接

由於業務需求，有贊本身造了不少輪子，組件庫尤爲多，React，Vue，小程序都有涉及，其餘開源項目有 zan-proxy 代理，PHP 的框架 zanphp 等。有人可能會以爲奇怪，爲何有贊要造這麼多輪子？其實緣由真的很簡單，就是由於現有的替代品沒法知足咱們自身業務的需求，多是不知足咱們的定製需求，也多是功能不符合咱們要求。根據業務須要，咱們總結了一套適合本身的套路、規範，並把這些套路、規範作成了工具、組件庫或者框架。php

這大概即是有贊內部啓動這些項目的原因了。後來，隨着這些項目的逐步完善，一個天然而然的想法就是把它們開源了，也許別人也有相似咱們的需求。前端

慢慢的，有讚的 Github 上就有了好多開源項目。在維護這些開源項目的過程當中咱們總結了一些經驗教訓，在此跟你們分享。git

1、有讚的 Github 使用姿式

Github 有必定的社交屬性，維護好一個開源項目除了代碼寫得好，有一些使用姿式也是很重要的，咱們總結了幾點跟你們分享。github

1. 一個好的 README 很重要

README 文件是項目給人的第一印象，所謂人靠衣裝馬靠鞍，開源項目有個好的臉面是很重要的，尤爲是當這個項目仍是一個前端項目的時候。針對 README 文件咱們給出如下幾點建議：golang

同一個組織的 README 統一格式
最好有個英文版的 README
加上開發指南的連接

統一 README 格式的好處是讓別人一眼就認出這個項目是某某公司或者某某人的，有贊內部就維護了一份 README 的規範。模版內容很簡單，可是它保證了咱們的項目有必定的識別度。小程序

英文版的 README 不是爲了裝逼，若是你篤定本身的用戶都在國內，那就只須要中文版的 README 就能夠了。可是大部分狀況下，項目維護者都但願本身的代碼可以幫助到更多人，包括國外的用戶，這時候英文 README 的價值就體現出來了。api

開發指南很容易被忽略，它存在的目是幫助那些但願加入項目開發的開發者們快速上手。做爲參與開源項目的開發者，他們對開發指南有哪些指望？我以爲無外乎幾點：bash

如何搭建開發環境？
有哪些未解決的問題須要幫助？
如何提交代碼？

若是開發指南可以回答這幾個問題，有經驗的開發者就能夠比較快的參與進來。babel

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 更加合適。

2、技巧分享

上面介紹了一些 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 的標題規範性不是那麼好，致使更新日誌的可讀性變得比較差。另一個問題是機器生成的更新日誌它無法作到把同一組件的修改歸類整理到一塊兒，這也是可讀性較差的一個緣由。

咱們如今的更新日誌是經過腳本先生成一份「草稿」，而後由包的發佈者在這個基礎上總結提煉出一份方便閱讀的更新日誌。這種方式增長了一些發佈者的工做量，可是更新日誌的可讀性有較大提高，投入產出比仍是能夠接受的。