semantic release

发表于 更新于 分类于 本文字数： 5.3k 阅读时长 ≈ 5 分钟

资源

资源 组织 类型
语义化发布 (Semantic release) sentimentalversioning 规范
semantic-release semantic-release 工具
semantic version semver 规范
semantic release gitbook semantic-release 文档

Semantic Release

Usage

1
2
# 本地测试
semantic-release -d --no-ci

Angular Standard Commit

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<type>(<scope>): <short summary>
  │       │             │
  │       │             └─⫸ Summary in present tense. Not capitalized. No period at the end.
  │       │
  │       └─⫸ Commit Scope: animations|bazel|benchpress|common|compiler|compiler-cli|core|
  │                          elements|forms|http|language-service|localize|platform-browser|
  │                          platform-browser-dynamic|platform-server|router|service-worker|
  │                          upgrade|zone.js|packaging|changelog|docs-infra|migrations|ngcc|ve|
  │                          devtools
  │
  └─⫸ Commit Type: build|ci|docs|feat|fix|perf|refactor|test

Commit Message Body

Commit Message Footer

links:

Common Conventional Commit

1
2
3
4
5
6
7
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

# Comment on https://www.conventionalcommits.org/en/v1.0.0/

提交说明包含了下面的结构化元素，以向类库使用者表明其意图：

  • fix: 类型 为 fix 的提交表示在代码库中修复了一个 bug（这和语义化版本中的 PATCH 相对应）。

  • feat: 类型 为 feat 的提交表示在代码库中新增了一个功能（这和语义化版本中的 MINOR 相对应）。

  • BREAKING CHANGE: 在脚注中包含 BREAKING CHANGE: 或 <类型>(范围) 后面有一个！的提交，表示引入了破坏性 API 变更（这和语义化版本中的 MAJOR 相对应）。 破坏性变更可以是任意 类型 提交的一部分。

  • 除 fix: 和 feat: 之外，也可以使用其它提交 类型 ，例如 @commitlint/config-conventional（基于 Angular 约定）中推荐的 build:、chore:、 ci:、docs:、style:、refactor:、perf:、test:，等等。

  • 脚注中除了 BREAKING CHANGE: ，其它条目应该采用类似 git trailer format 这样的惯例。

其它提交类型在约定式提交规范中并没有强制限制，并且在语义化版本中没有隐式影响（除非它们包含 BREAKING CHANGE）。 可以为提交类型添加一个围在圆括号内的范围，以为其提供额外的上下文信息。例如 feat (parser): adds ability to parse arrays.。

Release Workflow

常用的 release workflow 方式有如下 3 种：

QA

Integrate with CI

GitLab CI

links:

GitLab CI Configuration

links:

Github Action

要使用 semantic-release 工具配置项目的 GitHub Action 以实现自动化版本发布，需要做以下几步：

  • 安装 semantic-release 和相关插件。在项目的根目录下创建一个 package.json 文件，然后添加以下内容：

1
2
3
4
5
6
7
8
9
{
  "devDependencies": {
    "@semantic-release/changelog": "^6.0.1",
    "@semantic-release/git": "^10.0.1",
    "@semantic-release/commit-analyzer": "^9.0.1",
    "@semantic-release/release-notes-generator": "^11.0.2",
    "@semantic-release/github": "^8.0.1"
  }
}

然后运行 npm install 来安装这些依赖.

  • 创建一个.releaserc 文件来配置 semantic-release。在项目的根目录下创建一个.releaserc 文件，然后添加以下内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/changelog",
    "@semantic-release/github",
    [
      "@semantic-release/git",
      {
        "assets": ["CHANGELOG.md", "package.json"],
        "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
      }
    ]
  ]
}

  • 在 GitHub Actions 中配置 semantic-release。在.github/workflows 目录下创建一个新的 workflow 文件，例如 release.yml，然后添加以下内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
name: Release
on:
  push:
    branches:
      - main
jobs:
  release:
    name: Release
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: Setup Node.js
        uses: actions/setup-node@v2
        with:
          node-version: 14
      - name: Install dependencies
        run: npm ci
      - name: Release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: npx semantic-release

这个 workflow 会在每次 push 到 main 分支时运行，自动分析 commit messages 来决定新的版本号，然后创建一个新的 GitHub release。

links:

Semantic Release Plugin

links:

semantic-release/commit-analyzer

用于解析提交消息，并判断是否需要执行发布 release

links:

semantic-release/release-notes-generator

用于将 commit-analyzer 解析出的符合规范的提交消息筛选并根据规则 conventional changelog configuration spec 生成发布信息说明

links:

semantic-release/changelog

用于将 release-notes-generator 生成内容更新到 CHANGELOG.md

google/semantic-release-replace-plugin

用于在发布时替换内容.

在发布 release 时替换版本.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
[
  "@google/semantic-release-replace-plugin",
  {
    "replacements": [
      {
        "files": [
            "pyproject.toml"
        ],
        "from": "^version = \".*\"",
        "to": "version = \"${nextRelease.version}\"",
        "countMatches": true
      }
    ]
  }
]

links:

semantic-release/git

用于在触发发布时的提交更改回仓库，tag 将会创建在当前提交上

1
2
3
4
5
6
7
8
9
10
[
    "@semantic-release/git",
    {
        "assets": [
            "CHANGELOG.md",
        ],
        // disable ci run with [skip ci]
        "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
    }
]

links:

semantic-release/exec

语义发布插件执行自定义 shell 命令。

links: