提交分析器

semantic-release 插件，用于使用 conventional-changelog 分析提交

安装

$ npm install @semantic-release/commit-analyzer -D

使用方法

可以在 semantic-release 配置文件 中配置该插件：

{
  "plugins": [
    [
      "@semantic-release/commit-analyzer",
      {
        "preset": "angular",
        "releaseRules": [
          { "type": "docs", "scope": "README", "release": "patch" },
          { "type": "refactor", "release": "patch" },
          { "type": "style", "release": "patch" }
        ],
        "parserOpts": {
          "noteKeywords": ["BREAKING CHANGE", "BREAKING CHANGES"]
        }
      }
    ],
    "@semantic-release/release-notes-generator"
  ]
}

使用此示例：

• 在提交信息主体中包含 BREAKING CHANGE 或 BREAKING CHANGES 的提交将被视为重大变更。
• 类型为 'docs'、作用域为 'README' 的提交将与 patch 发布相关联
• 类型为 'refactor' 的提交将与 patch 发布相关联
• 类型为 'style' 的提交将与 patch 发布相关联

注意：您的提交必须完全按照所选约定指定的格式进行格式化。例如，Angular 提交消息约定要求 BREAKING CHANGE 关键字后面跟着冒号（:），并且必须位于提交消息的脚注中。

配置

选项

注意：为了使用 preset，必须先安装它（例如，要使用 eslint 预设，您必须使用 npm install conventional-changelog-eslint -D 安装它）

注意：config 将被 preset 的值覆盖。您应该使用 preset 或 config，但不能同时使用两者。

注意：parserOpts 的各个属性将覆盖显式设置的 preset 或 config 加载的属性。如果未设置 preset 或 config，则只会使用 parserOpts 中设置的属性。

注意：对于需要配置对象的预设，例如 conventionalcommits，必须设置 presetConfig 选项。

releaseRules

在决定自上次发布以来的提交是否需要新的发布时，会使用发布规则。如果您定义了自定义发布规则，当没有匹配项时将使用默认规则。这些规则将与 conventional-commits-parser 解析后的提交对象进行匹配。每个规则属性都可以定义为 glob。

规则定义

这是一个规则对象的 Array。规则对象具有一个 release 属性和一个或多个条件。

{
  "plugins": [
    [
      "@semantic-release/commit-analyzer",
      {
        "preset": "angular",
        "releaseRules": [
          { "type": "docs", "scope": "README", "release": "patch" },
          { "type": "refactor", "scope": "core-*", "release": "minor" },
          { "type": "refactor", "release": "patch" },
          { "scope": "no-release", "release": false }
        ]
      }
    ],
    "@semantic-release/release-notes-generator"
  ]
}

规则匹配

每个提交将与每条规则进行比较，当匹配时，该提交将与规则的 release 属性中的发布类型相关联。如果一个提交匹配多条规则，则与该提交相关联的发布类型将是最高的发布类型（major > minor > patch）。

有关发布类型层次结构，请参阅发布类型。

使用上面的示例：

• type 为 'docs' 且 scope 为 'README' 的提交将与 patch 发布相关联。
• type 为 'refactor' 且 scope 以 'core-' 开头的提交（例如 'core-ui'、'core-rules' 等）将与 minor 发布相关联。
• 其他 type 为 'refactor' 的提交（没有 scope 或 scope 不匹配 glob core-*）将与 patch 发布相关联。
• scope 为 no-release 的提交将不会与任何发布类型相关联。

默认规则匹配

如果一个提交不匹配 releaseRules 中的任何规则，它将根据默认发布规则进行评估。

使用上面的示例：

• 包含破坏性变更的提交将与"major"版本相关联。
• 类型为"feat"的提交将与"minor"版本相关联。
• 类型为"fix"的提交将与"patch"版本相关联。
• 类型为"perf"的提交将与"patch"版本相关联。
• 作用域为"no-release"的提交即使包含破坏性变更或类型为"feat"、"fix"或"perf"，也不会与任何版本类型相关联。

没有匹配的规则

如果一个提交不符合releaseRules中的任何规则或默认发布规则，则不会将任何发布类型与该提交相关联。

根据前面的例子：

• 类型为"style"的提交不会与任何发布类型相关联。
• 类型为"test"的提交不会与任何发布类型相关联。
• 类型为"chore"的提交不会与任何发布类型相关联。

多个提交

如果有多个提交符合一个或多个规则，具有最高发布类型的提交将决定全局发布类型。

考虑以下提交：

• docs(README): 为API文档添加更多细节
• feat(API): 向公共API添加一个新方法

根据前面的例子，插件确定的发布类型将是"minor"。

特定提交属性

规则中要设置的属性将取决于所选择的提交风格。例如，conventional-changelog-angular使用提交属性"type"、"scope"和"subject"，而conventional-changelog-eslint使用"tag"和"message"。

例如，使用"eslint"预设：

{
  "plugins": [
    [
      "@semantic-release/commit-analyzer",
      {
        "preset": "eslint",
        "releaseRules": [
          { "tag": "Docs", "message": "*README*", "release": "patch" },
          { "tag": "New", "release": "patch" }
        ]
      }
    ],
    "@semantic-release/release-notes-generator"
  ]
}

使用此配置：

• 标签为"Docs"且消息头包含"README"的提交将与"patch"版本相关联。
• 标签为"New"的提交将与"patch"版本相关联。
• 标签为"Breaking"的提交将与"major"版本相关联（根据默认发布规则）。
• 标签为"Fix"的提交将与"patch"版本相关联（根据默认发布规则）。
• 标签为"Update"的提交将与"minor"版本相关联（根据默认发布规则）。
• 所有其他提交不会与任何发布类型相关联。

外部包/文件

releaseRules也可以引用模块，可以通过npm名称或路径引用：

{
  "plugins": [
    [
      "@semantic-release/commit-analyzer",
      {
        "preset": "angular",
        "releaseRules": "./config/release-rules.cjs"
      }
    ],
    "@semantic-release/release-notes-generator"
  ]
}

// 文件：config/release-rules.cjs
module.exports = [
  { type: "docs", scope: "README", release: "patch" },
  { type: "refactor", scope: "core-*", release: "minor" },
  { type: "refactor", release: "patch" },
];