1---
2stage: none
3group: unassigned
4info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
5---
6
7# Changelog entries
8
9This guide contains instructions for when and how to generate a changelog entry
10file, as well as information and history about our changelog process.
11
12## Overview
13
14Each bullet point, or **entry**, in our
15[`CHANGELOG.md`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/CHANGELOG.md)
16file is generated from the subject line of a Git commit. Commits are included
17when they contain the `Changelog` [Git trailer](https://git-scm.com/docs/git-interpret-trailers).
18When generating the changelog, author and merge request details are added
19automatically.
20
21The `Changelog` trailer accepts the following values:
22
23- `added`: New feature
24- `fixed`: Bug fix
25- `changed`: Feature change
26- `deprecated`: New deprecation
27- `removed`: Feature removal
28- `security`: Security fix
29- `performance`: Performance improvement
30- `other`: Other
31
32An example of a Git commit to include in the changelog is the following:
33
34```plaintext
35Update git vendor to gitlab
36
37Now that we are using gitaly to compile git, the git version isn't known
38from the manifest, instead we are getting the gitaly version. Update our
39vendor field to be `gitlab` to avoid cve matching old versions.
40
41Changelog: changed
42```
43
44### Overriding the associated merge request
45
46GitLab automatically links the merge request to the commit when generating the
47changelog. If you want to override the merge request to link to, you can specify
48an alternative merge request using the `MR` trailer:
49
50```plaintext
51Update git vendor to gitlab
52
53Now that we are using gitaly to compile git, the git version isn't known
54from the manifest, instead we are getting the gitaly version. Update our
55vendor field to be `gitlab` to avoid cve matching old versions.
56
57Changelog: changed
58MR: https://gitlab.com/foo/bar/-/merge_requests/123
59```
60
61The value must be the full URL of the merge request.
62
63### GitLab Enterprise changes
64
65If a change is exclusively for GitLab Enterprise Edition, **you must add** the
66trailer `EE: true`:
67
68```plaintext
69Update git vendor to gitlab
70
71Now that we are using gitaly to compile git, the git version isn't known
72from the manifest, instead we are getting the gitaly version. Update our
73vendor field to be `gitlab` to avoid cve matching old versions.
74
75Changelog: changed
76MR: https://gitlab.com/foo/bar/-/merge_requests/123
77EE: true
78```
79
80**Do not** add the trailer for changes that apply to both EE and CE.
81
82## What warrants a changelog entry?
83
84- Any change that introduces a database migration, whether it's regular, post,
85  or data migration, **must** have a changelog entry, even if it is behind a
86  disabled feature flag.
87- [Security fixes](https://gitlab.com/gitlab-org/release/docs/blob/master/general/security/developer.md)
88  **must** have a changelog entry, with `Changelog` trailer set to `security`.
89- Any user-facing change **must** have a changelog entry. Example: "GitLab now
90  uses system fonts for all text."
91- Any client-facing change to our REST and GraphQL APIs **must** have a changelog entry.
92  See the [complete list what comprises a GraphQL breaking change](api_graphql_styleguide.md#breaking-changes).
93- Any change that introduces an [Advanced Search migration](elasticsearch.md#creating-a-new-advanced-search-migration)
94  **must** have a changelog entry.
95- A fix for a regression introduced and then fixed in the same release (such as
96  fixing a bug introduced during a monthly release candidate) **should not**
97  have a changelog entry.
98- Any developer-facing change (such as refactoring, technical debt remediation,
99  or test suite changes) **should not** have a changelog entry. Example: "Reduce
100  database records created during Cycle Analytics model spec."
101- _Any_ contribution from a community member, no matter how small, **may** have
102  a changelog entry regardless of these guidelines if the contributor wants one.
103- Any [GLEX experiment](experiment_guide/gitlab_experiment.md) changes **should not** have a changelog entry.
104- [Modifying](feature_flags/#changelog) a feature flag (flag removal, default-on setting).
105
106## Writing good changelog entries
107
108A good changelog entry should be descriptive and concise. It should explain the
109change to a reader who has _zero context_ about the change. If you have trouble
110making it both concise and descriptive, err on the side of descriptive.
111
112- **Bad:** Go to a project order.
113- **Good:** Show a user's starred projects at the top of the "Go to project"
114  dropdown.
115
116The first example provides no context of where the change was made, or why, or
117how it benefits the user.
118
119- **Bad:** Copy (some text) to clipboard.
120- **Good:** Update the "Copy to clipboard" tooltip to indicate what's being
121  copied.
122
123Again, the first example is too vague and provides no context.
124
125- **Bad:** Fixes and Improves CSS and HTML problems in mini pipeline graph and
126  builds dropdown.
127- **Good:** Fix tooltips and hover states in mini pipeline graph and builds
128  dropdown.
129
130The first example is too focused on implementation details. The user doesn't
131care that we changed CSS and HTML, they care about the _end result_ of those
132changes.
133
134- **Bad:** Strip out `nil`s in the Array of Commit objects returned from
135  `find_commits_by_message_with_elastic`
136- **Good:** Fix 500 errors caused by Elasticsearch results referencing
137  garbage-collected commits
138
139The first example focuses on _how_ we fixed something, not on _what_ it fixes.
140The rewritten version clearly describes the _end benefit_ to the user (fewer 500
141errors), and _when_ (searching commits with Elasticsearch).
142
143Use your best judgement and try to put yourself in the mindset of someone
144reading the compiled changelog. Does this entry add value? Does it offer context
145about _where_ and _why_ the change was made?
146
147## How to generate a changelog entry
148
149Git trailers are added when committing your changes. This can be done using your
150text editor of choice. Adding the trailer to an existing commit requires either
151amending to the commit (if it's the most recent one), or an interactive rebase
152using `git rebase -i`.
153
154To update the last commit, run the following:
155
156```shell
157git commit --amend
158```
159
160You can then add the `Changelog` trailer to the commit message. If you had
161already pushed prior commits to your remote branch, you have to force push
162the new commit:
163
164```shell
165git push -f origin your-branch-name
166```
167
168To edit older (or multiple commits), use `git rebase -i HEAD~N` where `N` is the
169last N number of commits to rebase. Let's say you have 3 commits on your branch:
170A, B, and C. If you want to update commit B, you need to run:
171
172```shell
173git rebase -i HEAD~2
174```
175
176This starts an interactive rebase session for the last two commits. When
177started, Git presents you with a text editor with contents along the lines of
178the following:
179
180```plaintext
181pick B Subject of commit B
182pick C Subject of commit C
183```
184
185To update commit B, change the word `pick` to `reword`, then save and quit the
186editor. Once closed, Git presents you with a new text editor instance to edit
187the commit message of commit B. Add the trailer, then save and quit the editor.
188If all went well, commit B is now updated.
189
190For more information about interactive rebases, take a look at [the Git
191documentation](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History).
192
193---
194
195[Return to Development documentation](index.md)
196