Changelog 条目
本指南包含何时以及如何生成 changelog 条目文件的说明，以及我们 changelog 流程的相关信息和历史记录。
概述
我们 CHANGELOG.md 文件中的每个列表项，即条目，都是从 Git 提交的主题行生成的。当提交包含 Changelog Git trailer 时，该提交会被包含在 changelog 中。生成 changelog 时，作者和合并请求的详细信息会自动添加。
有关 trailer 的列表，请参见 向 Git 提交添加 trailer。
以下是一个包含在 changelog 中的 Git 提交示例：
Update git vendor to GitLab
Now that we are using Gitaly to compile Git, the Git version isn't known
from the manifest. Instead, we are getting the Gitaly version. Update our
vendor field to be `gitlab` to avoid CVE matching old versions.
Changelog: changed如果你的合并请求包含多个提交，请确保将 Changelog 条目添加到第一个提交中。这样可以确保在提交被压缩时生成正确的条目。
覆盖关联的合并请求
生成 changelog 时，GitLab 会自动将合并请求链接到提交。如果你想覆盖要链接的合并请求，可以使用 MR trailer 指定另一个合并请求：
Update git vendor to gitlab
Now that we are using gitaly to compile git, the git version isn't known
from the manifest, instead we are getting the gitaly version. Update our
vendor field to be `gitlab` to avoid cve matching old versions.
Changelog: changed
MR: https://gitlab.com/foo/bar/-/merge_requests/123该值必须是合并请求的完整 URL。
GitLab Enterprise 变更
如果某个变更仅适用于 GitLab Enterprise Edition，你必须添加 EE: true trailer：
Update git vendor to gitlab
Now that we are using gitaly to compile git, the git version isn't known
from the manifest, instead we are getting the gitaly version. Update our
vendor field to be `gitlab` to avoid cve matching old versions.
Changelog: changed
MR: https://gitlab.com/foo/bar/-/merge_requests/123
EE: true不要为同时适用于 EE 和 CE 的变更添加此 trailer。
什么情况下需要 changelog 条目？
- 任何引入数据库迁移的变更，无论是常规迁移、后期迁移还是数据迁移，必须有 changelog 条目，即使它被禁用的功能标志所保护。
- 安全修复 必须有 changelog 条目，并将
Changelogtrailer 设置为security。 - 任何面向用户的变更 必须 有 changelog 条目。例如：“GitLab 现在为所有文本使用系统字体。”
- 对我们的 REST 和 GraphQL API 的任何面向客户端的变更 必须 有 changelog 条目。请参见 构成 GraphQL 破坏性变更的完整列表。
- 任何引入 高级搜索迁移 的变更 必须 有 changelog 条目。
- 对于在同一版本中引入并修复的回归修复（例如修复在月度发布候选版本中引入的错误）不应该有 changelog 条目。
- 任何面向开发者的变更（如重构、技术债务修复或测试套件变更）不应该有 changelog 条目。例如：“减少在 Cycle Analytics 模型规范期间创建的数据库记录。”
- 来自社区成员的任何贡献，无论多么微小，如果贡献者希望，可以有 changelog 条目，不受这些指南限制。
- 任何 实验 变更 不应该有 changelog 条目。
- 仅包含文档变更的合并请求 不应该有 changelog 条目。
有关更多信息，请参见 如何处理带有功能标志的 changelog 条目。
编写良好的 changelog 条目
良好的 changelog 条目应该既描述性又简洁。它应该向对变更零背景的读者解释变更。如果你难以同时做到简洁和描述性，倾向于描述性。
- 不好：转到项目订单。
- 好：在"转到项目"下拉列表顶部显示用户收藏的项目。
第一个示例没有提供变更发生的位置、原因或如何受益于用户的上下文。
- 不好：复制（某些文本）到剪贴板。
- 好：更新"复制到剪贴板"工具提示以指示正在复制的内容。
同样，第一个示例过于模糊，没有提供上下文。
- 不好：修复和改进小型流水线图和构建下拉列表中的 CSS 和 HTML 问题。
- 好：修复小型流水线图和构建下拉列表中的工具提示和悬停状态。
第一个示例过于关注实现细节。用户不关心我们更改了 CSS 和 HTML，他们关心这些变更的最终结果。
- 不好：从
find_commits_by_message_with_elastic返回的提交对象数组中去除nil值。 - 好：修复由 Elasticsearch 结果引用已回收提交导致的 500 错误。
第一个示例关注我们如何修复问题，而不是修复了什么。重写版本清楚地描述了用户的最终收益（更少的 500 错误）和何时（使用 Elasticsearch 搜索提交时）。
运用你的最佳判断，尝试将自己置于阅读已编译 changelog 的人的思维模式中。这个条目是否增加了价值？它是否提供了关于变更发生位置和原因的上下文？
如何生成 changelog 条目
Git trailer 在提交你的更改时添加。这可以使用你选择的文本编辑器完成。向现有提交添加 trailer 需要修改提交（如果它是最近的提交）或使用 git rebase -i 进行交互式变基。
要更新最后一个提交，运行以下命令：
git commit --amend然后你可以将 Changelog trailer 添加到提交消息中。如果你已经将先前的提交推送到远程分支，你必须强制推送新提交：
git push -f origin your-branch-name要编辑较旧的（或多个）提交，使用 git rebase -i HEAD~N，其中 N 是要变基的最后 N 个提交。例如，如果你的分支上有三个提交，并且只想更新第二个提交，你需要运行：
git rebase -i HEAD~2这将启动最后两个提交的交互式变基会话。启动时，Git 会向你显示一个文本编辑器，内容如下：
pick B 提交 B 的主题
pick C 提交 C 的主题要更新提交 B，将单词 pick 更改为 reword，然后保存并退出编辑器。关闭后，Git 会向你显示一个新的文本编辑器实例来编辑提交 B 的提交消息。添加 trailer，然后保存并退出编辑器。如果一切顺利，提交 B 现在已更新。
由于你更改了已存在于远程分支中的提交，在推送到远程分支时必须使用 --force-with-lease 标志：
git push origin your-branch-name --force-with-lease有关交互式变基的更多信息，请查看 Git 文档。