跳至主要内容

[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），像是 ：

'@semantic-release/commit-analyzer';
'@semantic-release/github';
'@semantic-release/npm';
'@semantic-release/release-notes-generator';

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

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

設定 .releaserc.json​

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

// .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 中進行設定：

// .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 進專案的檔案包括：

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

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

// .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 執行的過程中出現類似的錯誤訊息時：

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

可以修改 .travis.yaml 的檔案，將 script 的地方改成：

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

下一步​

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

Imgur

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

參考​