快來利用 Github 這個功能來建立讓本身滿意的項目模版吧

時間 2019-11-05

標籤快來利用 github 這個功能建立本身滿意項目模版欄目 Git 简体版

原文原文鏈接

我認可我實在想不出更好的標題了，由於本文涉及到的內容比較寬泛。但我保證，本文會盡量作到拋磚引玉的效果。不只僅是建立項目模版，寫項目的時候須要考慮的東西本文也適合。javascript

本文主要會講如下幾個內容：前端

Github 的模版倉庫功能
開源項目（模版）要考慮的 9 個工程化要素
一些建立項目（模版）時提高效率的技巧

閱讀過程當中能夠同時參考我寫的一個模版倉庫樣例，若有經常使用 TypeScript 和 VSCode 的讀者，食用起來會更佳。java

背景

開源社區有不少工具能夠幫助開發者快速生成一個我的項目，但有時候你可能會遇到如下問題：node

工具生成的項目過於複雜，不少東西都不必
生成過程當中設置了不少問題，每次都回答一遍很繁瑣
生成項目後仍須要修修改改，加上本身喜歡的一些內容
找不到徹底適用於本身的模版

或許你已經從零開始或基於相似 Yeoman 的工具開發了一個本身的腳手架，但其實 Github 建立模板倉庫的功能就能夠知足你的需求。react

這個功能適合知足如下條件的項目模版：git

項目模版徹底定製化，而非通用化。這意味着沒法像 CLI 工具同樣經過設置問題來替換模版中相應的內容，從而作到不一樣喜愛的人也能經過選擇來生成本身想要的項目。github

因此，若是你常常建立我的項目，而且每次都和前幾回架構差很少，那麼經過這種方法來建立本身的模版是再簡單不過了。typescript

如何作到滿意

在講 Github 的模版倉庫功能以前，咱們先來談一談建立一個模版倉庫須要考慮哪些問題，才能使得這個倉庫讓本身滿意。畢竟你須要從零開始建立一個倉庫，才能在 Github 上將它設爲模版倉庫。npm

通常來講，開發者老是會對本身的項目感到滿意，即使之後學了新的知識發現原來很糟糕。這是由於建立項目時的所做所爲已經達到了本身的現有水平，從而得到了知足感。編程

因此，咱們在創建項目的時候，應該經過對比當時一些知名的開源項目來創建滿意度，而不是基於本身現有水平來創建。它們的高度更高，產生滿意的情緒更難。可是一旦滿意，那麼你的項目高度也就上去了。

接下來，我會列舉 9 個開源項目要考慮的工程化要素，而且給出一些建立項目模版時快速達到該工程化目標的技巧，但願能給你們一些啓示。

TypeScript

若是你準備建立的項目知足如下任一條件，那麼你就該考慮使用 TypeScript 來編寫你的項目了：

從時間上看，是有可能中長期更新或者維護的項目
從空間上看，項目不是很小，有必定複雜度
從情感上看，想要引入類型系統讓本身舒心，或者喜歡寫類型和接口

Tips

本地安裝 typescript 後，可使用 npx tsc --init 來生成一份 tsconfig.json 文件。該文件列有 TypeScript 全部的配置，你只須要取消相應配置的註釋就能夠啓用它了。這個配置最好放在項目模版裏，免得每次都要複製粘貼。
若是你的項目模版是 Node 相關的，別忘了在 package.json 中加入 @types/node。

編碼規範

一個項目須要有統一的編程風格和規範，通常來講，使用 EditorConfig 來規範編輯器的格式，使用 ESLint 來檢查代碼錯誤和規範編程風格。市面上最流行的 ESLint 規範應該是 Airbnb JavaScript Style Guide 和 JavaScript Standard Style 這兩個了。

Tips

若是你使用 VSCode，能夠安裝一個 EditorConfigGenerator 插件來快速生成一份 .editorconfig 文件。
本地安裝好 eslint 以後，可使用 npx eslint --init 來快速生成一份本身想要的 .eslintrc.js 的配置。
若是你使用 TypeScript 語言和 VSCode 來開發，你或許還須要在項目模版根目錄下新建一個 .vscode 目錄，而且在該目錄下新建一個 settings.json 文件，寫下如下內容，以便啓用 VSCode 中 ESLint 插件的自動修復功能：
```
{
    "eslint.validate": [
        "javascript",
        "javascriptreact",
        {
            "language": "typescript",
            // 這個屬性就表明要對 typescript 語言啓用自動修復功能
            "autoFix": true
        }
    ]
}
複製代碼
```
配置好後，即可以在 VSCode 的命令面板中找到 ESLint: Fix all auto-fixable Problems 進行自動修復了：

測試框架

一個良好的開源項目必定是要有比較高的測試覆蓋率的，因此選擇一個測試框架來寫測試代碼相當重要。我比較喜歡 Jest，由於上手容易，一個包就能解決不少訴求，同時有大廠背書，比較適合我的開源項目。

關於 Jest 的一些核心配置能夠閱讀這篇文章

Tips

本地安裝好 jest 以後，可使用 npx jest --init 來快速生成一份 jest.config.js 配置文件。

Commit 規範

優秀的開源項目每每都有規範、容易閱讀的 Commit 信息，咱們能夠藉助一些工具來幫助咱們達到目的。主要是從如下兩點入手：

在寫 Commit 信息時提醒如何填寫關鍵信息，例如提交類型、涉及更改的文件等；

爲了實現這一點，咱們能夠藉助 husky 來指定 prepare-commit-msg 鉤子觸發時執行的命令，也就是在 git commit 運行後立馬執行的命令。該命令實際執行的程序可使用 commitizen。在 package.json 中這樣寫：
```
{
    // 其餘配置......
    "husky": {
        "hooks": {
            "prepare-commit-msg": "exec < /dev/tty && git cz --hook || true"
        }
    }
    // 其餘配置......
}
複製代碼
```
commitizen 就是一款提示你如何填寫 Commit 的命令行工具，可經過 git cz 直接調用。它自己不包含 Commit 規範，須要另外安裝一個規範庫來搭配使用。比較流行的規範是 Angular 團隊的 Commit 規範，對應的包是 cz-conventional-changelog。你須要在 package.json 中寫下以下配置才能讓 commitizen 使用這個規範：
```
{
    // 其餘配置......
    "config": {
        "commitizen": {
            "path": "./node_modules/cz-conventional-changelog"
        }
    }
    // 其餘配置......
}
複製代碼
```

提交 Commit 信息時驗證其是否符合 Commit 規範。

要實現這一點，咱們一樣要藉助 husky，在 commit-msg 鉤子這執行檢驗 Commit 的命令。負責這一命令的工具是 @commitlint/cli，它也不包含校驗的規則，須要另外安裝 @commitlint/config-conventional 來讓 commitlint 明確是按 Angular 團隊的規範來校驗 Commit 信息。在 pakcage.json 這樣寫：

{
    // 其餘配置......
    "husky": {
        "hooks": {
            "prepare-commit-msg": "exec < /dev/tty && git cz --hook || true",
            // husky 新增的配置，運行 commitlint 命令
            "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
        }
    },
    // commitlint 配置
    "commitlint": {
        "extends": [
            // commitlint 校驗的規範標準
            "@commitlint/config-conventional"
        ]
    }
    // 其餘配置......
}
複製代碼

上述兩個內容配置好後，當你運行 git commit 的時候，會產生如下的效果：

CI / CD

優秀的開源項目都會有自動化測試，而在提交代碼的時候必須經過測試才能合到主分支，這個測試過程就能夠放到 CI 上來進行。另外，若是你的項目還涉及到構建、部署等，那就更須要 CI / CD 了。

對於在 Github 上開源的項目來講，Github Actions 就是一個很是不錯的選擇。

Github Actions 首次使用須要用戶去它的官網申請，申請好了之後，就會發現本身的全部倉庫中都會有個 Actions 的選項卡，這裏面就能看到該倉庫 CI / CD 的狀況。

因此，在你的項目或項目模版裏，能夠新建一個 .github 目錄，而且在該目錄下新建一個 workflows 目錄，而後在這個目錄下隨便建一個 .yml 文件，通常叫 build.yml，由於在 README 的徽章裏會使用這個名字，若是 CI / CD 經過的話，則這個徽章會顯示綠色，而且文字是 build passing。

例如，若是你的項目須要跑一下測試，build.yml 裏面就能這麼寫：

# 持續集成工做流
# 語法：https://help.github.com/cn/articles/workflow-syntax-for-github-actions

name: build

on: push

# 任務
jobs:
    # 測試任務
 test:
 name: test
        # 運行環境
 runs-on: ${{ matrix.os }}

        # 構建矩陣，讓任務在如下平臺和 Node 版本中都跑一遍
 strategy:
 matrix:
 os: [ubuntu-latest, windows-latest, macOS-latest]
 node: [6, 8, 10]

        # 運行步驟
 steps:
        # actions/checkout 爲必須的，用於拉取代碼到虛擬環境中
 - uses: actions/checkout@v1
        # actions/setup-node 非必須的，這裏使用只是爲了後續可使用各類版本的 node
 - uses: actions/setup-node@v1
 with:
 node-version: ${{ matrix.node }}
 - run: | npm i npm run test 複製代碼

想要了解更多 Github Actions 的內容，能夠直接查看官方的中文文檔，寫的挺詳細的。

文檔

良好的 README 文件可以使你的項目更容易理解和使用，多語言的 README 更會使你的項目大放異彩。通常 README.md 文件是英文文檔，README.zh-CN.md 是中文文檔。強烈建議新手按照 Standard Readme Style 規範來編寫本身的文檔，多寫幾遍，你就明白 README 該寫些什麼東西了。

CHANGELOG

幾乎每個開源項目都會寫 CHANGELOG，它和 README 同樣重要。請注意，CHANGELOG 是寫給將來的本身或參與項目的其餘人看的，更是寫給用戶看的。因此這裏就不推薦自動把 Commit 拼湊成 CHANGELOG 的工具了，除非你的 Commit 信息寫的足夠人性化，那麼你卻是能夠用一用 conventional-changelog。

我更建議新手手動寫 CHANGELOG，和 README 同樣，CHANGELOG 在社區也有一套 keep a changelog 規範，它會教你如何把 CHANGELOG 寫好。