PJCHENder 未整理筆記

[Guide] 發佈 npm 套件 - 從手動到自動(6):semantic-release 的外掛設定與自動產生 CHANGELOG

2020-02-19

[Guide] 發佈 npm 套件 - 從手動到自動(6):semantic-release 的外掛設定與自動產生 CHANGELOG

keywords: deploy, publish, release, CLI, npm, package.json

semantic-release

上一篇文章中已經有透露如果要對 semantic-release 套用外掛(plugin)或進行更多的設定,可以在根目錄建立一支 .releaserc.json 的檔案,現在我們一樣可以透過這支檔案,來讓 semantic-release 自動產生 CHANGELOG.md 的檔案。

安裝 semantic-release 外掛

預設的情況下,semantic-release 就已經安裝了幾個外掛(plugin),像是 :

1
2
3
4
"@semantic-release/commit-analyzer"
"@semantic-release/github"
"@semantic-release/npm"
"@semantic-release/release-notes-generator"

為了要產生 CHANGELOG 檔案,並且保存推進 git 中,需要再安裝 @semantic-release/changelog@semantic-release/git 這兩個外掛:

1
$ npm install @semantic-release/changelog @semantic-release/git -D

設定 .releaserc.json

接著在根目錄底下新增一隻 .releaserc.json 的檔案(如果已經建過就不用重複新增),在這支檔案裡貼上:

1
2
3
4
5
6
7
8
9
10
// .releaserc.json
{
"plugins": [
"@semantic-release/commit-analyzer",
"@semantic-release/release-notes-generator",
"@semantic-release/changelog",
"@semantic-release/npm",
"@semantic-release/git"
]
}

建立好設定檔後,commit 並推上 Github,這時候在 Travis CI 持續整合的過程中,就會新增一支 CHANGELOG.md 的檔案在根目錄了:

Imgur

這裡你可以注意到:

  1. 最後的 git commit 是由 semantic-release-bot 所建立的,這是透過 @semantic-release/git 這個套件達到的。
  2. 不知道你先前有沒有發現到,之前雖然每次推上 Github 或發佈到 npm 上時的版號都有不斷更新,但 git 中 package.json 檔案裡面的版號卻都沒有改變,這同樣是因為之前沒有安裝 @semantic-release/git 的關係,所以雖然 Github 和 npm 上的版號更新了,但因為 semantic-release 沒有把更新後的 package.json 檔 commit 回我們的 repository,所以本機 package.json 中的版號才會都沒有更動。
  3. CHANGELOG.md 檔案的內容有更新了,這是透過 @semantic-release/changelog 這個套件達到的。CHANGELOG 中的內容會依據 commit 的內容進行更新:

Imgur

semantic-release 的外掛設定

在了解如何產生 CHANGELOG.md 檔,並透過 @semantic-release/git 來把變更的內容推回 git 後,我們可以再來看一下 semantic-release 外掛的設定:

@semantic-release/changelog

@semantic-release/changelog 這個套件中,預設會在根目錄新增一支 CHANGELOG.md 的檔案,如果你想要修改 CHANGELOG 檔放置的路徑或標題(title),一樣可以在 .releaserc.json 中進行設定:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// .releaserc.json
{
"plugins": [
"@semantic-release/commit-analyzer",
"@semantic-release/release-notes-generator",
// 修改 changelog 檔預設的路徑和標題
["@semantic-release/changelog", {
"changelogFile": "docs/CHANGELOG.md",
"changelogTitle": "This is Title"
}],
// 預設會 commit 根目錄的 CHANGELOG.md 檔,因此要告訴它說去其他路徑取得 CHANGELOG 檔
["@semantic-release/git", {
"assets": ["docs/CHANGELOG.md"],
}]
]
}

@semantic-release/git

透過 @semantic-release/git 這個套件,可以告訴 semantic-release 哪些檔案是它可以 commit 進我們的專案,並且可以修改 commit 的訊息。預設的情況下它可以 commit 進專案的檔案包括:

1
['CHANGELOG.md', 'package.json', 'package-lock.json', 'npm-shrinkwrap.json']

如果檔案的路徑有變更,或者有些檔案是打包後才產生,希望可以大家可以透過 github 取得的,一樣可以在這裡進行設定,以下面的設定為例,除了 CHANGELOG.md, package.jsonpackage-lock.json 會進 git 之外,我們把打包後會產生的 extension.zip 檔案也進 git,如此使用者便會在 Github 上看得到這隻檔案:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// .releaserc.json
{
"plugins": [
"@semantic-release/commit-analyzer",
"@semantic-release/release-notes-generator",
"@semantic-release/changelog",
["@semantic-release/git", {
"assets": [
"CHANGELOG.md",
"package.json",
"package-lock.json",
"extension.zip"
]
}]
]
}

@semantic-release/npm

如我你的套件並不需要發佈到 npm 上,除了可以透過上一篇的方式,設定 npmPublish: false 外,也可以在 .releaserc.json 中把 @semantic-release/npm 移掉也可以達到一樣的效果。

錯誤處理:在 Travis CI 上使用出現 Cannot find module 的問題

如果你在 Travis CI 執行的過程中出現類似的錯誤訊息時:

1
2
Cannot find module '@semantic-release/changelog'
Cannot find module '@semantic-release/git'

可以修改 .travis.yaml 的檔案,將 script 的地方改成:

1
script: npx -p @semantic-release/changelog -p @semantic-release/git -p semantic-release semantic-release

下一步

現在我們已經完成了 semantic-release 的基本設定,透過 semantic-release 可以幫助我們省下不少的時間,自動更新套件版號自動發佈套件到 npm,以及自動產生 CHANGELOG 檔等等…。在下一篇文章中,將會說明如何套用大家在 README 中常見各種標章(badge):

Imgur

其中最重要的就是測試覆蓋率拉!就讓我們到下一篇中說明吧!

參考

掃描二維條碼,分享此文章