Skip to main content

[Deploy] Semantic Release 筆記

keywords: deploy, publish, release, CLI, CI#
# 在 local 執行 dry-run
$ NPM_TOKEN=<your_npm_token> GH_TOKEN=<your_github_token> npx semantic-release --no-ci --dry-run

注意事項#

  • sematic-release 的設定檔 .releaserc 副檔名雖然可以是 js,但裡面還是得要使用 JSON 語法(Configuration File)。
  • 在 Travis CI 上執行 semantic-release 時有可能會發生「Can not find modules」的錯誤,解決方式可參考下面「[在 Travis CI 上使用出現 Cannot find module 的問題](#在 Travis CI 上使用出現 Cannot find module 的問題)」。

semantic-release#

Introduction @ semantic-release gitbooks

目的:透過 semantic-release 可以自動化整個套件發佈的工作流程,包含決定 next version 的版號、產生 release notes 和發佈套件。semantic-release 使用 commit 的內容來決定專案版本變更的類型,並且自動產生語易化版號,產生 changelog 和發佈。

撰寫 commit:預設著情況下 semantic-release 使用 Angular Commit Message Conventions 來決定版號的變更,有需要的話,亦可透過 @semantic-release/commit-analyzer@semantic-release/release-notes-generatorpresetconfig 選項來調整。

格式化 commit 的工具:也可以使用像是 commitizencommitlint 這類的工具來幫助開發者強制寫出合法有效的 commit messages。

CI:semantic-release 是用來 CI 環境中,每次成功打包後執行。對於每一個透過 git push 或 merge PR 到 release branch(例如,master, next, beta)的 commit,CI 都會觸發打包和執行 semantic-release 指令以產生新的 release

步驟:在執行 semantic-release 的指令後,會執行這些步驟

Getting Started#

要使用 semantic-release 的話,需要依序完成下列步驟:

  1. 安裝:在專案中安裝 semantic-release
  2. 設定 CI 服務:設定 CI 服務(例如,Travis CI, Github Action)來執行 semantic-release
  3. 設定 CI 權限:在 CI 服務中設定 Github 和套件管理工具的權限
  4. 建立設定檔:設定 semantic-release 的外掛和選項

可以透過 semantic-release cli 來簡化上述的部分流程。

Plugin#

Plugins @ semantic-release

預設就有的外掛包含:

"@semantic-release/commit-analyzer"
"@semantic-release/github"
"@semantic-release/npm"
"@semantic-release/release-notes-generator"

自動產生 CHANGE_LOG 檔案#

若有需要自動產生 CHANGE_LOG 檔案:

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

設定檔如下:

// .releaserc.json
{
plugins: [
'@semantic-release/commit-analyzer',
'@semantic-release/release-notes-generator',
[
'@semantic-release/changelog',
{
changelogFile: 'docs/CHANGELOG.md',
},
],
'@semantic-release/npm,
[
'@semantic-release/git',
{
// 寫在 assets 裡的內容可以在 CI 後被 commit 到 git repository 內
// 預設是 ['CHANGELOG.md', 'package.json', 'package-lock.json', 'npm-shrinkwrap.json']
assets: ['docs/CHANGELOG.md'],
},
],
],
};

semantic-release CLI#

semantic-release cli @ github

這個工具會自動產生 Github 和 NPM 上的 Token 並設定到 Travis 上:

$ npm install -g semantic-release-cli
$ cd your-module
$ semantic-release-cli setup

其他#

authentication 建立給 semantic-release 用的 Github Token#

使用 semantic-release 時需要建立帶有對應權限的 github personal token 和 npm token 給它

在 Travis CI 上使用出現 Cannot find module 的問題#

How to automatically pull changelog and git modules when issuing npx semantic-release? @ Github Issues

在 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

參考設定檔#

.releaserc#

// .releaserc.json
{
"plugins": [
"@semantic-release/commit-analyzer",
"@semantic-release/release-notes-generator",
"@semantic-release/changelog",
[
"@semantic-release/npm",
{
"npmPublish": false, // 要不要發佈到 npm
"tarballDir": "dist"
}
],
"@semantic-release/git"
]
}

Travis#

# .travis.yaml
language: node_js
node_js:
- 12
jobs:
include:
# Define the release stage that runs semantic-release
- stage: release
node_js: lts/*
script: npm run build
deploy:
provider: script
script: npx -p @semantic-release/changelog -p @semantic-release/git -p semantic-release semantic-release
skip_cleanup: true # 💡加上這句
Last updated on