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