更新日志条目
本指南包含有关何时以及如何生成变更日志条目文件的说明，以及有关变更日志过程的信息和历史记录。
概述
每个要点，或者条目，在我们的CHANGELOG.md中的单个数据文件生成更新日志/未释放(或相应的EE)文件夹。该文件预计为YAML文件格式如下:
---标题：”改变(日志)年代”merge_request：1972作者：黑色安息日类型：添加的merge_request值是对添加此条目的合并请求的引用，而作者Key用于向社区贡献者提供归属。两者都是可选的。的类型字段映射更改的类别，有效选项有:添加、固定、更改、弃用、删除、安全、性能、其他。类型字段是必须的。
鼓励社区贡献者和核心团队成员将他们的名字添加到作者字段。GitLab团队成员不应该。
是什么保证了一个变更日志条目?
- 任何面向用户的更改应该有一个变更日志条目。示例:“GitLab现在对所有文本使用系统字体。”
- 对引入的回归进行修复，然后在同一版本中进行修复(例如，修复每月候选版本中引入的错误)不应该有一个变更日志条目。
- 任何面向开发人员的变更(例如，重构、技术债务补救、测试套件变更)不应该有一个变更日志条目。示例:“减少Cycle Analytics模型规范期间创建的数据库记录。”
- 任何社区成员的贡献，无论多么小，五月如果贡献者想要一个更改日志条目，而不考虑这些指导方针。示例:“修复了搜索结果页面上的一个错别字。(简·史密斯)”
- 性能改进应该有一个变更日志条目。
写好更新日志条目
一个好的变更日志条目应该是描述性的和简洁的。它应该向已经读过的读者解释这种变化零上下文关于变化。如果你无法做到既简洁又具有描述性，那就选择描述性。
- 缺点:转到项目订单。
- 好:在“Go to project”下拉菜单的顶部显示用户的星号项目。
第一个示例没有提供在何处进行更改、更改原因或更改如何使用户受益的上下文。
- 缺点:把[一些文字]复制到剪贴板上。
- 好:更新“复制到剪贴板”工具提示，以指示复制的内容。
同样，第一个例子太模糊，没有提供上下文。
- 缺点:修复和改进了迷你管道图中的CSS和HTML问题，并构建了下拉菜单。
- 好:修复了工具提示和悬停状态在迷你管道图和构建下拉列表。
第一个示例过于关注实现细节。用户并不关心我们是否改变了CSS和HTML，他们关心的是最终结果这些变化。
- 缺点:剔除
零返回的Commit对象数组中find_commits_by_message_with_elastic - 好:修复了由elasticsearch结果引用垃圾收集提交引起的500个错误
第一个例子的重点是如何我们修好了一些东西，不是on什么它修复。改写后的版本清楚地描述了最终受益对于用户(少于500个错误)，和当(使用Elasticsearch搜索提交)。
运用你最好的判断力，试着把自己放在一个正在阅读已编译的变更日志的人的心态中。这个条目有价值吗?它是否提供了上下文在哪里和为什么改变了吗?
如何生成变更日志条目
一个bin /更新日志脚本可用于自动生成changelog条目文件。
它最简单的用法是提供for的值标题：
“嘿，DZ，我给GitLab增加了一个特性!”此时，脚本将要求您选择更改的类别(映射到类型栏位):
>>请注明更改的类别:1.新功能2.错误修复3.功能变化4.新弃用5.功能删除6.安全补丁7.其他条目文件名基于当前Git分支的名称。如果在一个名为特性/ hey-dz，它会生成a更新日志/未发表/ feature-hey-dz.yml文件。
该命令将输出生成文件的路径及其内容:
创建变更/未发表/ my-feature.yml---标题:嘿，DZ，我给GitLab添加了一个功能!merge_request:作者:类型:如果您正在使用GitLab EE存储库，则该条目将被添加到ee /变更/未释放代替。
参数
| 论点 | 速记 | 目的 |
|---|---|---|
——修改 |
修改之前的提交 | |
——力 |
- f |
覆盖现有条目 |
——merge-request |
- m |
设置合并请求ID |
——即将 |
- n |
不要写任何东西，只是打印 |
——git-username |
- u |
使用Git user.name configuration作为作者 |
——类型 |
- t |
更改的类别，有效选项有:添加、固定、更改、弃用、删除、安全、其他 |
——帮助 |
- h |
打印帮助信息 |
——修改
你可以通过——修改参数自动执行生成的文件并将其修改为上次提交。
如果你使用——修改不要提供标题，它会自动使用前一次提交的“主题”，即提交消息的第一行:
$ git show - onlineab88683为GitLab添加了一个很棒的新功能$ bin/changelog——修改创建变更/未发表/ feature-hey-dz.yml---标题:为GitLab添加了一个很棒的新功能merge_request:作者:类型:——力或- f
使用——力或- f覆盖已存在的更改日志项。
“嘿，DZ，我给GitLab增加了一个特性!”错误的更新日志/未发表/ feature-hey-dz。Yml已经存在了!使用“——force”来覆盖。“嘿，DZ，我给GitLab增加了一个特性!”——力创建变更/未发表/ feature-hey-dz.yml---标题:嘿，DZ，我给GitLab添加了一个功能!merge_request: 1983作者:类型:——merge-request或- m
使用——merge-request或- m参数来提供merge_request值:
“嘿，DZ，我给GitLab增加了一个特性!”- m1983创建变更/未发表/ feature-hey-dz.yml---标题:嘿，DZ，我给GitLab添加了一个功能!merge_request: 1983作者:类型:——即将或- n
使用——即将或- n参数以防止实际编写或提交任何内容:
$ bin/changelog—modify—dry-run创建变更/未发表/ feature-hey-dz.yml---标题:为GitLab添加了一个很棒的新功能merge_request:作者:类型:$ ls changlogs /unreleased/——git-username或- u
使用——git-username或- u参数来自动填充作者值与配置的Gituser.name值:
$ git配置user.name简母鹿$ bin/changelog -u '嘿，DZ，我给GitLab添加了一个特性!'创建变更/未发表/ feature-hey-dz.yml---标题:嘿，DZ，我给GitLab添加了一个功能!merge_request:作者:简·多伊类型:——类型或- t
使用——类型或- t参数来提供类型值:
“嘿，DZ，我给GitLab增加了一个特性!”- t添加创建变更/未发表/ feature-hey-dz.yml---标题:嘿，DZ，我给GitLab添加了一个功能!merge_request:作者:类型:添加历史与推理
我们的更新日志文件以前是由每个贡献者手动更新的，他们认为他们的更改需要一个条目。当两个合并请求在列表中的同一位置添加它们自己的条目时，一旦另一个合并，它就会在其中一个中创建合并冲突。当我们有几十个合并请求争夺同一个变更日志条目位置时，这很快就成为合并冲突和开发延迟的主要来源。
这让我们想到了无聊的解决方案"将你的条目随机添加到列表的某个位置"当我们在每个月的发行周期中向前推进时，这种方法便能够有效地发挥作用，但在新周期开始时，当新版本部分被添加时，能够“随机”添加条目的地方便会减少，冲突便会再次成为一个问题，直到我们拥有足够数量的条目。
最重要的是，它造成了一个完全不同的头痛发布经理当他们挑选一个提交到一个稳定的分支来发布补丁时。中的一个条目更新日志，它将包括最新版本的整个更改日志主，因此发布经理将不得不手动删除后面的条目。他们通常不得不在每个补丁版本中多次这样做。由于安全问题，我们不得不一次发布多个补丁，这使情况更加复杂。
我们需要将所有这些手工工作自动化。所以我们开始头脑风暴。经过多次讨论，我们确定了当前每个条目一个文件的解决方案，然后将条目编译为整体CHANGELOG.md文件期间发布过程。