极狐 GitLab

变更日志条目

我们的 CHANGELOG.md 文件中的每个列表项，或 条目，都是从 Git 提交的主题行生成的。当提交包含 Changelog Git 尾部 时，这些提交会被包含。在生成变更日志时，作者和合并请求的详细信息会自动添加。

如何生成变更日志条目#

Git 尾部是在提交更改时添加的。你可以使用你选择的文本编辑器来完成。要添加变更日志：

  1. 选择适合你用例的尾部。

    一个包含在变更日志中的 Git 提交示例如下：

    plaintext
    将 Git 供应商更新为极狐GitLab

现在我们使用 Gitaly 来编译 Git，因此 Git 版本无法从清单中得知。相反，我们获取的是 Gitaly 版本。将我们的供应商字段更新为 `gitlab`，以避免 CVE 匹配旧版本。

变更日志：已更改

  2. 推送你的更改。

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

将尾部添加到现有提交需要修改提交（如果它是最新的），或者使用 git rebase -i 进行交互式变基。

  • 要更新最后一次提交，请运行以下命令：

    shell
    git commit --amend

    然后，你可以将 Changelog 尾部添加到提交消息中。如果你已经将之前的提交推送到了远程分支，则必须强制推送新提交：

    shell
    git push -f origin your-branch-name

  • 要编辑更早的（或多个）提交，请使用 git rebase -i HEAD~N，其中 N 是要变基的最后 N 个提交数。例如，如果你的分支上有三个提交，并且只想更新第二个提交，则需要运行：

    shell
    git rebase -i HEAD~2

    这将为最后两个提交启动一个交互式变基会话。启动后，Git 会显示一个文本编辑器，内容大致如下：

    plaintext
    pick B 提交 B 的主题
pick C 提交 C 的主题

    要更新提交 B，请将单词 pick 改为 reword，然后保存并退出编辑器。关闭后，Git 会打开一个新的文本编辑器实例，用于编辑提交 B 的提交消息。添加尾部，然后保存并退出编辑器。如果一切顺利，提交 B 现在已更新。

    由于你更改了远程分支中已存在的提交，因此在推送到远程分支时必须使用 --force-with-lease 标志：

    shell
    git push origin your-branch-name --force-with-lease

有关交互式变基的更多信息，请参阅 Git 文档。

覆盖关联的合并请求#

极狐GitLab 在生成变更日志时，会自动将合并请求链接到提交。如果你想覆盖要链接的合并请求，可以使用 MR 尾部指定一个替代的合并请求：

plaintext
1将 Git 供应商更新为 gitlab
2
3现在我们使用 gitaly 来编译 git，因此 git 版本无法从清单中得知。相反，我们获取的是 gitaly 版本。将我们的供应商字段更新为 `gitlab`，以避免 cve 匹配旧版本。
4
5变更日志：已更改
6MR: https://jihulab.com/foo/bar/-/merge_requests/123

该值必须是合并请求的完整 URL。

极狐GitLab 企业版变更#

如果某项更改仅适用于极狐GitLab 企业版，你必须添加 EE: true 尾部：

plaintext
1将 Git 供应商更新为 gitlab
2
3现在我们使用 gitaly 来编译 git，因此 git 版本无法从清单中得知。相反，我们获取的是 gitaly 版本。将我们的供应商字段更新为 `gitlab`，以避免 cve 匹配旧版本。
4
5变更日志：已更改
6MR: https://jihulab.com/foo/bar/-/merge_requests/123
7EE: true

不要为同时适用于企业版和基础版的更改添加此尾部。

什么情况下需要变更日志条目？#

  • 任何引入数据库迁移的更改，无论是常规迁移、部署后迁移还是数据迁移，必须有一个变更日志条目，即使它在一个禁用的功能标志之后。
  • 安全修复 必须有一个变更日志条目，并将 Changelog 尾部设置为 security。
  • 任何面向用户的更改必须有一个变更日志条目。例如："极狐GitLab 现在对所有文本使用系统字体。"
  • 任何面向客户端的 REST 和 GraphQL API 更改必须有一个变更日志条目。请参阅 构成 GraphQL 破坏性变更的完整列表。
  • 任何引入 高级搜索迁移 的更改必须有一个变更日志条目。
  • 在同一版本中引入并修复的回归修复（例如修复月度发布候选版本中引入的错误）不应有变更日志条目。
  • 任何面向开发者的更改（例如重构、技术债务修复或测试套件更改）不应有变更日志条目。例如："减少 Cycle Analytics 模型规范期间创建的数据库记录。"
  • 来自社区成员的_任何_贡献，无论多小，如果贡献者希望，可以有一个变更日志条目，而不受这些准则的限制。
  • 任何 实验 更改不应有变更日志条目。
  • 仅包含文档更改的 MR 不应有变更日志条目。

有关更多信息，请参阅 如何处理带有功能标志的变更日志条目。

编写良好的变更日志条目#

一个好的变更日志条目应该描述性强且简洁。它应该向对更改_一无所知_的读者解释该更改。如果你难以同时做到简洁和描述性，请偏向描述性。

  • 差：转到项目顺序。
  • 好：在“转到项目”下拉列表的顶部显示用户的星标项目。

第一个示例没有提供更改的位置、原因或对用户的好处。

  • 差：将（某些文本）复制到剪贴板。
  • 好：更新“复制到剪贴板”的工具提示，以指示正在复制的内容。

同样，第一个示例过于模糊，没有提供上下文。

  • 差：修复和改进迷你流水线图和构建下拉列表中的 CSS 和 HTML 问题。
  • 好：修复迷你流水线图和构建下拉列表中的工具提示和悬停状态。

第一个示例过于关注实现细节。用户不关心我们更改了 CSS 和 HTML，他们关心这些更改的_最终结果_。

  • 差：从 find_commits_by_message_with_elastic 返回的 Commit 对象数组中去除 nil
  • 好：修复由于 Elasticsearch 结果引用已垃圾回收的提交而导致的 500 错误

第一个示例关注我们_如何_修复问题，而不是修复了_什么_。重写的版本清楚地描述了用户的_最终收益_（减少 500 错误），以及_何时_（使用 Elasticsearch 搜索提交时）。

请运用你的最佳判断，并尝试站在阅读编译后变更日志的人的角度思考。这个条目是否增加了价值？它是否提供了有关更改的_位置_和_原因_的上下文？

返回开发文档