变更日志 | 极狐GitLab

将 trailer 添加到 Git 提交中
创建变更日志
- 从 API
- 从极狐GitLab CLI
自定义变更日志输出
处理已还原的提交
相关主题

Tier: 基础版，专业版，旗舰版
Offering: JihuLab.com，私有化部署

极狐GitLab 中的变更日志是根据提交标题和 Git trailers 生成的。要包含在变更日志中，提交必须包含特定的 Git trailer。变更日志是从提交标题生成的，并根据 Git trailer 类型进行分类。您可以使用其他数据丰富变更日志条目，例如链接到合并请求或提交作者的详细信息。变更日志格式可以使用模板进行自定义。

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

## 1.0.0 (2021-01-05)

### Features (4 changes)

- [Feature 1](gitlab-org/gitlab@123abc) by @alice ([merge request](gitlab-org/gitlab!123))
- [Feature 2](gitlab-org/gitlab@456abc) ([merge request](gitlab-org/gitlab!456))
- [Feature 3](gitlab-org/gitlab@234abc) by @steve
- [Feature 4](gitlab-org/gitlab@456)

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

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

在镜像上操作时，可以检索变更日志的提交。极狐GitLab 本身使用此功能，因为补丁发布可以包括来自公共项目和私人安全镜像的更改。

将 trailer 添加到 Git 提交中

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

<Commit message subject>

<Commit message description>

Changelog: feature

创建变更日志

变更日志是通过命令行生成的，可以使用 API 或极狐GitLab CLI。变更日志输出采用 Markdown 格式，您可以自定义它。

从 API

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

从极狐GitLab CLI

在 glab 版本 1.30.0 中引入。

先决条件：

您已安装并配置了极狐GitLab CLI，版本为 1.30.0 或更高。
您的存储库的标签命名方案与预期的标签命名格式相匹配。
提交包括变更日志 trailers。

要生成变更日志：

使用 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：一个哈希，用于将原始类别名称映射到变更日志中使用的名称。要更改在变更日志中显示的名称，请将这些行添加到配置文件中并根据需要进行编辑。此示例将类别标题渲染为 ### 功能、### Bug 修复 和 ### 性能改进：
```
---
categories:
  feature: Features
  bug: Bug fixes
  performance: Performance improvements
```

自定义模板

默认模板在极狐GitLab 17.1 中从 commit.reference 和 merge_request.reference 更改为 commit.web_url 和 merge_request.web_url。

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

{% if categories %}
{% each categories %}
### {{ title }} ({% if single_change %}1 change{% else %}{{ count }} changes{% end %})

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

{% end %}

{% end %}
{% else %}
No changes.
{% end %}

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

例如，对于一个名为 valid 的变量，您可以显示 “yes” 当该值为 true，并在其他情况下显示 “nope”：

{% if valid %}
yes
{% else %}
nope
{% end %}

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

循环使用 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 %}
  No changes.
  {% end %}

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

模板数据

commit.web_url 和 merge_request.web_url 在极狐GitLab 17.1 中引入。

在顶层，可以使用以下变量：

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 trailers。

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

Add some impressive new feature

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

可以在模板中访问 Changelog、Issue 和 Status trailers，如下所示：

{% each entries %}
{% if commit.trailers.Issue %} ([link to issue]({{ commit.trailers.Issue }})){% end %}
{% if commit.trailers.Status %}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: Flowchart of 3 commits accDescr: Shows the flow of 3 commits, where commit C reverts commit B, but it contains no trailer A[Commit A Changelog: changed] --> B[Commit B Changelog: changed] B --> C[Commit C Reverts commit B]

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

%%{init: { "fontFamily": "GitLab Sans" }}%% graph LR accTitle: Flowchart of 3 commits accDescr: Shows the flow of 3 commits, where commit C reverts commit B, but both commits A and C contain trailers A[Commit A Changelog: changed] --> B[Commit B Changelog: changed] B --> C[Commit C Reverts commit B Changelog: changed]

提交 B 被跳过。