Help us learn about your current experience with the documentation. Take the survey.

变更日志

Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

变更日志基于提交标题和 Git trailer 生成。要包含在变更日志中，提交必须包含特定的 Git trailer。变更日志从提交标题生成，并按 Git trailer 类型分类。您可以使用额外数据丰富变更日志条目，例如合并请求链接或提交作者详细信息。变更日志格式可以自定义为模板。

默认变更日志中的每个部分都有一个包含版本号和发布日期的标题，如下所示：

## 1.0.0 (2021-01-05)

### 功能 (4 项变更)

- [功能 1](gitlab-org/gitlab@123abc) by @alice ([合并请求](gitlab-org/gitlab!123))
- [功能 2](gitlab-org/gitlab@456abc) ([合并请求](gitlab-org/gitlab!456))
- [功能 3](gitlab-org/gitlab@234abc) by @steve
- [功能 4](gitlab-org/gitlab@456)

部分的日期格式可以自定义，但标题的其他部分不能。添加新部分时，GitLab 会解析这些标题以确定在文件中放置新信息的位置。GitLab 根据版本对部分进行排序，而不是日期。

每个部分包含按类别（如"功能"）排序的变更，这些部分的格式可以更改。部分名称源自用于包含或排除提交的 Git trailer 的值。

变更日志的提交可以在操作镜像时检索。GitLab 本身使用此功能，因为补丁版本可以包含公共项目和私有安全镜像中的变更。

向 Git 提交添加 trailer

您可以在编写提交消息时手动添加 trailer。要使用默认的 Changelog trailer 包含提交并将其分类为功能，请将字符串 Changelog: feature 添加到您的提交消息中，如下所示：

<提交消息主题>

<提交消息描述>

Changelog: feature

如果您的合并请求有多个提交，请将 Changelog 条目添加到第一个提交中。这确保在您压缩提交时生成正确的条目。

Changelog trailer 接受以下值：

added: 新功能
fixed: 错误修复
changed: 功能变更
deprecated: 新弃用
removed: 功能移除
security: 安全修复
performance: 性能改进
other: 其他

创建变更日志

变更日志从命令行生成，使用 API 或 GitLab CLI。变更日志输出格式为 Markdown，您可以自定义它。

从 API 生成

要使用 API 通过 curl 命令生成变更日志，请参阅 API 文档中的向变更日志文件添加变更日志数据。

从 GitLab CLI 生成

先决条件：

您已安装并配置了 GitLab CLI，版本 1.30.0 或更高。
您的仓库的标签命名模式符合预期的标签命名格式。
提交包含变更日志 trailer。

要生成变更日志：

使用 git fetch 更新您的本地仓库副本。
为当前版本（由 git describe --tags 确定）生成具有默认选项的变更日志：
- 运行命令 glab changelog generate。
- 要将输出保存到文件，运行命令 glab changelog generate > <filename>.md。
要生成具有自定义选项的变更日志，运行命令 glab changelog generate 并附加您所需的选项。一些选项包括：
- --config-file [string]: 您项目 Git 仓库中变更日志配置文件的路径。该文件必须存在于您的项目 Git 仓库中。默认为 .gitlab/changelog_config.yml。
- 提交范围：
  - --from [string]: 用于生成变更日志的提交范围的起始点（作为 SHA）。此提交本身不包含在变更日志中。
  - --to [string]: 用于生成变更日志的提交范围的结束点（作为 SHA）。此提交包含在列表中。默认为默认项目分支的 HEAD。
- --date [string]: 发布的日期和时间，采用 ISO 8601 (2016-03-11T03:45:40Z) 格式。默认为当前时间。
- --trailer [string]: 用于包含提交的 Git trailer。默认为 Changelog。
- --version [string]: 生成变更日志的版本。

要了解 GitLab CLI 中可用的参数，请运行 glab changelog generate --help。查看 API 文档了解定义和用法。

自定义变更日志输出

要自定义变更日志输出，请编辑变更日志配置文件，并将这些更改提交到您的项目 Git 仓库。此配置的默认位置是 .gitlab/changelog_config.yml。

出于性能和安全原因，变更日志配置的解析限制为 2 秒。如果解析配置导致超时错误，请考虑减小配置的大小。该文件支持以下变量：

date_format: 在新添加的变更日志数据标题中使用的日期格式，采用 strftime 格式。
template: 生成变更日志数据时使用的自定义模板。
include_groups: 包含用户完整路径的列表，无论项目成员身份如何，都应为其贡献提供署名。生成变更日志的用户必须有权访问每个组才能给予署名。
categories: 将原始类别名称映射到变更日志中使用的名称的哈希。要更改变更日志中显示的名称，请将这些行添加到您的配置文件中并进行编辑以满足您的需求。此示例将类别标题渲染为 ### 功能、### 错误修复 和 ### 性能改进：
```
---
categories:
  feature: 功能
  bug: 错误修复
  performance: 性能改进
```

自定义模板

类别部分使用模板生成。默认模板：

{% if categories %}
{% each categories %}
### {{ title }} ({% if single_change %}1 项变更{% else %}{{ count }} 项变更{% end %})

{% each entries %}
- [{{ title }}]({{ commit.web_url }})\
{% if author.credit %} by {{ author.reference }}{% end %}\
{% if merge_request %} ([合并请求]({{ merge_request.web_url }})){% end %}

{% end %}

{% end %}
{% else %}
无变更。
{% end %}

{% ... %} 标签用于语句，{{ ... }} 用于打印数据。语句必须使用 {% end %} 标签终止。if 和 each 语句都需要一个参数。

例如，对于名为 valid 的变量，当此值为真时可以显示"是"，否则显示"否"，如下所示：

{% if valid %}
是
{% else %}
否
{% end %}

使用 else 是可选的。当值为非空值或布尔值 true 时，该值被视为真。空数组和哈希被视为假。

循环使用 each 完成，循环内的变量作用域限定在循环内。引用循环中的当前值使用变量标签 {{ it }}。其他变量从当前循环值读取其值。以这个模板为例：

{% each users %}
{{name}}
{% end %}

假设 users 是一个对象数组，每个对象都有一个 name 字段，这将打印每个用户的名称。

使用变量标签，您可以访问嵌套对象。例如， {{ users.0.name }} 打印 users 变量中第一个用户的名称。

如果一行以反斜杠结尾，则忽略下一个换行符。这允许您将代码跨多行包装，而不会在 Markdown 输出中引入不必要的换行符。

使用 {% 和 %} 的标签（称为表达式标签）会直接跟随它们的换行符（如果有）。这意味着：

---
{% if foo %}
bar
{% end %}
---

编译为：

---
bar
---

而不是：

---

bar

---

您可以在配置中指定自定义模板，如下所示：

---
template: |
  {% if categories %}
  {% each categories %}
  ### {{ title }}

  {% each entries %}
  - [{{ title }}]({{ commit.web_url }})\
  {% if author.credit %} by {{ author.reference }}{% end %}

  {% end %}

  {% end %}
  {% else %}
  无变更。
  {% end %}

指定模板时应使用 template: | 而不是 template: >，因为后者不保留模板中的换行符。

模板数据

在顶层，以下变量可用：

categories: 一个对象数组，每个变更日志类别一个。

在类别中，以下变量可用：

count: 此类别中的条目数量。
entries: 属于此类别的条目。
single_change: 一个布尔值，指示是否只有一项变更（true），或多项变更（false）。
title: 类别的标题（在重新映射后）。

在条目中，以下变量可用（这里 foo.bar 表示 bar 是 foo 的子字段）：

author.contributor: 当作者不是项目成员时设置为 true 的布尔值，否则为 false。
author.credit: 当 author.contributor 为 true 或当配置了 include_groups 且作者是其中一个组的成员时设置为 true 的布尔值。
author.reference: 对提交作者的引用（例如，@alice）。
commit.reference: 对提交的引用，例如， gitlab-org/gitlab@0a4cdd86ab31748ba6dac0f69a8653f206e5cfc7。
commit.web_url: 提交的 URL，例如， https://gitlab.com/gitlab-org/gitlab/-/commit/0a4cdd86ab31748ba6dac0f69a8653f206e5cfc7。

commit.trailers: 包含提交正文中存在的所有 Git trailer 的对象。

可以使用 commit.trailers.<name> 引用这些 trailer。例如，假设以下提交：

添加一些令人印象深刻的新功能

Changelog: added
Issue: https://gitlab.com/gitlab-org/gitlab/-/issues/1234
Status: important

可以在模板中按如下方式访问 Changelog、Issue 和 Status trailer：

{% each entries %}
{% if commit.trailers.Issue %} ([链接到问题]({{ commit.trailers.Issue }})){% end %}
{% if commit.trailers.Status %}状态: {{ commit.trailers.Status }}{% end %}
{% end %}

merge_request.reference: 首次引入变更的合并请求的引用（例如，gitlab-org/gitlab!50063）。
merge_request.web_url: 首次引入变更的合并请求的 URL（例如，https://gitlab.com/gitlab-org/gitlab/-/merge_requests/50063）。
title: 变更日志条目的标题（这是提交标题）。

如果无法确定数据，author 和 merge_request 对象可能不存在。例如，当提交创建时没有相应的合并请求，则不显示合并请求。

自定义提取版本时的标签格式

GitLab 使用正则表达式（使用 re2 引擎和语法）从标签名称中提取语义版本。默认正则表达式是：

^v?(?P<major>0|[1-9]\d*)\.(?P<minor>0|[1-9]\d*)\.(?P<patch>0|[1-9]\d*)(?:-(?P<pre>(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:(?P<meta>[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$

此正则表达式基于官方的语义版本控制正则表达式，还包括对以字母 v 开头的标签名称的支持。

如果您的项目使用不同的标签格式，您可以指定不同的正则表达式。使用的正则表达式必须生成以下捕获组。如果缺少任何这些捕获组，则忽略该标签：

major
minor
patch

以下捕获组是可选的：

pre: 如果设置，则忽略该标签。忽略 pre 标签确保在确定生成变更日志的提交范围时，不考虑候选版本标签和其他预发布标签。
meta: 可选。指定构建元数据。

使用此信息，GitLab 构建 Git 标签及其发布版本的映射。然后根据从每个标签提取的版本确定最新标签是什么。

要指定自定义正则表达式，请在您的变更日志配置 YAML 文件中使用 tag_regex 设置。例如，此模式匹配诸如 version-1.2.3 之类的标签名称，但不匹配 version-1.2。

---
tag_regex: '^version-(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)$'

要测试您的正则表达式是否正常工作，您可以使用诸如 regex101 之类的网站。如果正则表达式语法无效，则在生成变更日志时会产生错误。

回滚提交处理

要被视为回滚提交，提交消息必须包含字符串 This reverts commit <SHA>，其中 SHA 是要回滚的提交的 SHA。

在为范围生成变更日志时，GitLab 忽略在该范围内添加和回滚的提交。在此示例中，提交 C 回滚了提交 B。由于提交 C 没有其他 trailer，只有提交 A 被添加到变更日志中：

%%{init: { "fontFamily": "GitLab Sans" }}%%
graph LR
    accTitle: 3 个提交的流程图
    accDescr: 显示 3 个提交的流程，其中提交 C 回滚提交 B，但它不包含 trailer
    A[提交 A<br>Changelog: changed] --> B[提交 B<br>Changelog: changed]
    B --> C[提交 C<br>回滚提交 B]

但是，如果回滚提交（提交 C）也包含变更日志 trailer，则提交 A 和 C 都包含在变更日志中：

%%{init: { "fontFamily": "GitLab Sans" }}%%
graph LR
    accTitle: 3 个提交的流程图
    accDescr: 显示 3 个提交的流程，其中提交 C 回滚提交 B，但提交 A 和 C 都包含 trailer
    A[提交 A<br><br>Changelog: changed] --> B[提交 B<br><br>Changelog: changed]
    B --> C[提交 C<br>回滚提交 B<br>Changelog: changed]

提交 B 被跳过。