怎樣讓開源項目看起來「高大上」

時間 2019-12-04

標籤怎樣開源項目看起來高大简体版

原文原文鏈接

爲了不重複造輪子，咱們每每會藉助開源的項目實現一些功能。不少時候，選擇使用哪個開源項目就像選擇男、女友同樣，當然內在很重要，可是眼緣也很關鍵，只有看對了眼，纔會進一步地瞭解。做爲開源項目的開發者，固然是但願本身寫出來的成果能被更多的人嘗試使用，因此這篇文章主要談一談怎樣讓開源項目看起來「高大上」，從而讓別人有使用的衝動。html

首先要弄清楚一個問題：怎樣的開源項目纔算「高大上」呢？這裏舉出兩個例子，一個是在 2017 年愈來愈火的前端框架 Vue，還有一個是我所在團隊大神 avwo 開源的 web 調試代理工具 whistle，你們能夠去他們的 Github 地址感覺一下，下面展現一下他們 Readme 的開頭部分：前端

在我我的看來，一個「高大上」的 Github 上的開源項目應該知足這些條件：vue

一句話說明項目的功能；
有相對完善的測試用例和較高的代碼覆蓋率；
經過徽章明確地指出項目的兼容性、最新版本、被使用狀況、License 等；
有詳盡地 CHANGELOG 或者 release notes，也就是更新說明；
有簡介、明瞭的 commit 信息；
提供 discord、Telegram（國外）、QQ 羣或者微信羣（國內）等供使用者交流的地方；
利用 Github 能力提供 issue 和 pull request 的模板。

注意：上述排名分前後，若是有能力提供有一個美觀、獨特的 Logo，固然更好 🙃。ios

接下來會以我最近剛寫的一個小項目 git-master-merged 爲例，說一說如何利用 Github 和相關平臺的能力實現上面提到的內容，說的很差或者錯誤的地方歡迎你們指出來。git

簡潔的說明

在每個 Github 項目的最上方，都有一小塊地方讓咱們來填寫項目的描述、相關連接和對應的主題。也許是由於地兒過小了，你們沒注意，這裏都是空白的一片。不過不能由於塊頭小就小瞧呀，那潘長江還活不活了！悄悄地告訴你們，Github 的搜索功能就是根據這裏的描述和主題進行的，因此這裏最好能一句話講清楚項目的功能和做用，從而既能方便別人快速瞭解，也能讓更多人搜索到該項目，例如這樣：github

如今愈來愈多的項目喜歡在描述的開頭加上一個 emoji 表情，能夠參考這份 emoji 列表，將形如 :xxxx: 的短語粘貼便可展現成表情。web

完善的測試

「可靠性」這個詞現在被頻繁的提起，假如一個開源的項目沒有任何測試代碼，那麼怎麼能奢求別人在生產環境中使用呢？各個語言都有不一樣的測試框架，如 JavaScript 的 mocha、jest，Python 的 unittest 等，基本用法和概念都類似，這裏就不贅述了。這兒主要談談**持續集成（Continuous integration，簡稱CI）**在開源項目中的應用。segmentfault

因爲開源項目迭代速度較快，並且常常會收到別人的 pull request，因此如何在快速迭代中，保持較高的質量成爲了一個重要的問題。經過持續集成，咱們能夠在本身 commit 或者在接收他人 pull request 時，自動觸發測試代碼的執行，從而能經過測試結果快速、直觀地發現錯誤，讓質量獲得保障。bash

git-master-merged 項目所使用的持續集成工具是 Travis CI，對於 Github 上的開源項目，能夠無償使用。使用起來也很是簡單，一共只有四步：前端框架

用 Github 帳號登陸 https://travis-ci.org/；
選擇要使用 Travis CI 的項目：
在項目中添加 .travis.yml，通常在該文件中指定語言和測試環境；
commit 剛剛做出的修改，並推向 Github 倉庫。

（更詳細的說明能夠參考官方文檔）

假如一切順利的話，就能夠在 Travis CI 的後臺看到經過的結果，從而使用 build: passing 的徽章：

除了測試用例是否經過外，測試代碼的覆蓋率也是一個很重要的指標。咱們也能夠經過持續集成的方式，在 .travis.yml 文件中添加相關字段的說明，從而在 codecov 等網站上自動檢測 diamante 覆蓋率，從而再領取一枚徽章。

個性化的徽章

看到這些勳章是否是內心就有點癢癢的，想盡快爲本身的項目也添加上？這裏強烈推薦 http://shields.io/ 這個網址，經過它，咱們能夠爲項目添加上各類各樣的徽章，例如：

項目的最新版本；
項目的被使用狀況；
項目的兼容狀況；
測試是否經過以及代碼覆蓋率狀況；
代碼質量和風格狀況。

若是上述這些功能都不能知足你的話，還能夠自定義專屬於本身的勳章！這裏有一篇 GitHub 項目徽章的添加和設置詳細介紹的文章，我就很少說了，你們趕快用起來吧 :smile:

規範的提交記錄和更新說明

規範的提交記錄和更新說明，既可讓使用者清楚地知道更新的內容從而有更強的意願進行升級，也可讓項目參與者瞭解項目的演進歷史和當前情況從而更好地進行後續開發。再者，規範的提交記錄，能夠在出現問題時，快速地定位，找到錯誤代碼，從而解決問題（也能夠更快地知道是誰犯了錯👻）。

當前社區中使用較多的 commit 提交規範是 Angular 規範，英文文檔能夠閱讀 Git Commit Message Conventions，中文詳盡的介紹能夠閱讀 Commit message 和 Change log 編寫指南，這裏簡要地介紹一下：

commit 的格式包含 Header、Body、Footer 三個部分，形如：

<type>(<scope>): <subject>

<body>

<footer>
複製代碼

其中，Header 是必須，Body 和 Footer 能夠省略。進一步，Header 中，說明影響範圍的 scope 能夠省略，可是表示種類的 type 和 subject 必須包含，其中 type 只能從下列 7 中標識選取：

feat：新功能
fix：修補 bug
docs：文檔
style：格式化代碼
refactor：重構
test：完善測試
chore：其它維護相關更改

人老是不可靠的，有了規範以後，咱們能夠經過相關工具來提交和檢查提交記錄，並自動生成更新說明：

使用 commitizen 來進行交互式的 commit 提交，從而減小不規範的狀況；
使用 commitlint 來檢查不規範的 commit 提交，從而提出不規範的記錄；
使用 conventional-changelog 來自動地根據 commit 中 feat、fix、Performance Improvement 和 Breaking Changes 生成更新說明，並且是增量更新，並不會覆蓋已有的文件內容。

這裏經過幾張圖片瞭解一下：

清晰的模板

對於開源項目而言，他人給項目提 issue 或者 pull request 都是十分頻繁的，做爲項目的開發者或者維護者，最但願他人提供的信息是簡潔、明瞭且有用的。經過 github 提供的能力，咱們能夠編寫一套模板，讓他人在使用時直接往其中填入內容便可。整個過程也十分簡單：

在項目根目錄下建立目錄 .github；
編寫文件 .github/issue_template.md 文件：

### Expected behavior


### Actual behavior


### Steps to reproduce the behavior
複製代碼

變動提交至 github 並觀察效果：

官方文檔能夠參考：

Creating an issue template for your repository

Creating a pull request template for your repository

寫在最後

仍是拿談戀愛舉例子吧，「外在決定兩我的在一塊兒，內在決定兩我的在一塊兒多久」，一個看起來「高大上」的門面固然能夠吸引更多的人來使用咱們的項目，可是隻有項目自己具備較高的價值並積極運營時，才能留下用戶，讓項目更好地運做下去。

但願開源社區能發展地愈來愈好！

博客原文連接

相關標籤/搜索

每日一句

每一个你不满意的现在，都有一个你没有努力的曾经。