BigW Consortium Gitlab

changelog.md 10.4 KB
Newer Older
1
# Changelog entries
2

3 4
This guide contains instructions for when and how to generate a changelog entry
file, as well as information and history about our changelog process.
5 6 7 8 9 10 11 12 13 14 15 16 17

## Overview

Each bullet point, or **entry**, in our [`CHANGELOG.md`][changelog.md] file is
generated from a single data file in the [`changelogs/unreleased/`][unreleased]
(or corresponding EE) folder. The file is expected to be a [YAML] file in the
following format:

```yaml
---
title: "Going through change[log]s"
merge_request: 1972
author: Ozzy Osbourne
18
type: added
19 20 21 22
```

The `merge_request` value is a reference to a merge request that adds this
entry, and the `author` key is used to give attribution to community
23
contributors. **Both are optional**.
24 25
The `type` field maps the category of the change,
valid options are: added, fixed, changed, deprecated, removed, security, other. **Type field is mandatory**.
26

27
Community contributors and core team members are encouraged to add their name to
28
the `author` field. GitLab team members **should not**.
29 30 31 32 33

[changelog.md]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/CHANGELOG.md
[unreleased]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/changelogs/
[YAML]: https://en.wikipedia.org/wiki/YAML

34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56
## What warrants a changelog entry?

- Any user-facing change **should** have a changelog entry. Example: "GitLab now
  uses system fonts for all text."
- A fix for a regression introduced and then fixed in the same release (i.e.,
  fixing a bug introduced during a monthly release candidate) **should not**
  have a changelog entry.
- Any developer-facing change (e.g., refactoring, technical debt remediation,
  test suite changes) **should not** have a changelog entry. Example: "Reduce
  database records created during Cycle Analytics model spec."
- _Any_ contribution from a community member, no matter how small, **may** have
  a changelog entry regardless of these guidelines if the contributor wants one.
  Example: "Fixed a typo on the search results page. (Jane Smith)"

## Writing good changelog entries

A good changelog entry should be descriptive and concise. It should explain the
change to a reader who has _zero context_ about the change. If you have trouble
making it both concise and descriptive, err on the side of descriptive.

- **Bad:** Go to a project order.
- **Good:** Show a user's starred projects at the top of the "Go to project"
  dropdown.
57 58 59 60

The first example provides no context of where the change was made, or why, or
how it benefits the user.

61 62 63
- **Bad:** Copy [some text] to clipboard.
- **Good:** Update the "Copy to clipboard" tooltip to indicate what's being
  copied.
64 65 66

Again, the first example is too vague and provides no context.

67 68 69 70 71
- **Bad:** Fixes and Improves CSS and HTML problems in mini pipeline graph and
  builds dropdown.
- **Good:** Fix tooltips and hover states in mini pipeline graph and builds
  dropdown.

72 73 74 75 76 77 78 79 80 81 82 83 84
The first example is too focused on implementation details. The user doesn't
care that we changed CSS and HTML, they care about the _end result_ of those
changes.

- **Bad:** Strip out `nil`s in the Array of Commit objects returned from
  `find_commits_by_message_with_elastic`
- **Good:** Fix 500 errors caused by elasticsearch results referencing
  garbage-collected commits

The first example focuses on _how_ we fixed something, not on _what_ it fixes.
The rewritten version clearly describes the _end benefit_ to the user (fewer 500
errors), and _when_ (searching commits with ElasticSearch).

85 86 87 88 89
Use your best judgement and try to put yourself in the mindset of someone
reading the compiled changelog. Does this entry add value? Does it offer context
about _where_ and _why_ the change was made?

## How to generate a changelog entry
90 91 92 93 94 95 96

A `bin/changelog` script is available to generate the changelog entry file
automatically.

Its simplest usage is to provide the value for `title`:

```text
97
$ bin/changelog 'Hey DZ, I added a feature to GitLab!'
98 99
```

100 101 102 103 104 105 106 107 108 109 110 111 112
At this point the script would ask you to select the category of the change (mapped to the `type` field in the entry):

```text
>> Please specify the category of your change:
1. New feature
2. Bug fix
3. Feature change
4. New deprecation
5. Feature removal
6. Security fix
7. Other
```

113 114 115 116 117 118 119
The entry filename is based on the name of the current Git branch. If you run
the command above on a branch called `feature/hey-dz`, it will generate a
`changelogs/unreleased/feature-hey-dz.yml` file.

The command will output the path of the generated file and its contents:

```text
120 121 122 123 124
create changelogs/unreleased/my-feature.yml
---
title: Hey DZ, I added a feature to GitLab!
merge_request:
author:
125
type:
126
```
127 128 129 130
If you're working on the GitLab EE repository, the entry will be added to
`changelogs/unreleased-ee/` instead.

#### Arguments
131

132 133 134 135 136 137 138 139 140
| Argument            | Shorthand | Purpose                                                                                                    |
| -----------------   | --------- | ---------------------------------------------------------------------------------------------------------- |
| [`--amend`]         |           | Amend the previous commit                                                                                  |
| [`--force`]         | `-f`      | Overwrite an existing entry                                                                                |
| [`--merge-request`] | `-m`      | Set merge request ID                                                                                       |
| [`--dry-run`]       | `-n`      | Don't actually write anything, just print                                                                  |
| [`--git-username`]  | `-u`      | Use Git user.name configuration as the author                                                              |
| [`--type`]          | `-t`      | The category of the change, valid options are: added, fixed, changed, deprecated, removed, security, other |
| [`--help`]          | `-h`      | Print help message                                                                                         |
141

142 143 144 145 146
[`--amend`]: #-amend
[`--force`]: #-force-or-f
[`--merge-request`]: #-merge-request-or-m
[`--dry-run`]: #-dry-run-or-n
[`--git-username`]: #-git-username-or-u
147
[`--type`]: #-type-or-t
148
[`--help`]: #-help
149

150
##### `--amend`
151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168

You can pass the **`--amend`** argument to automatically stage the generated
file and amend it to the previous commit.

If you use **`--amend`** and don't provide a title, it will automatically use
the "subject" of the previous commit, which is the first line of the commit
message:

```text
$ git show --oneline
ab88683 Added an awesome new feature to GitLab

$ bin/changelog --amend
create changelogs/unreleased/feature-hey-dz.yml
---
title: Added an awesome new feature to GitLab
merge_request:
author:
169
type:
170 171
```

172
##### `--force` or `-f`
173 174 175 176 177 178 179 180 181 182 183 184 185 186

Use **`--force`** or **`-f`** to overwrite an existing changelog entry if it
already exists.

```text
$ bin/changelog 'Hey DZ, I added a feature to GitLab!'
error changelogs/unreleased/feature-hey-dz.yml already exists! Use `--force` to overwrite.

$ bin/changelog 'Hey DZ, I added a feature to GitLab!' --force
create changelogs/unreleased/feature-hey-dz.yml
---
title: Hey DZ, I added a feature to GitLab!
merge_request: 1983
author:
187
type:
188 189
```

190
##### `--merge-request` or `-m`
191 192 193 194 195

Use the **`--merge-request`** or **`-m`** argument to provide the
`merge_request` value:

```text
196
$ bin/changelog 'Hey DZ, I added a feature to GitLab!' -m 1983
197 198 199 200 201
create changelogs/unreleased/feature-hey-dz.yml
---
title: Hey DZ, I added a feature to GitLab!
merge_request: 1983
author:
202
type:
203 204
```

205
##### `--dry-run` or `-n`
206 207 208 209 210 211 212 213 214 215 216

Use the **`--dry-run`** or **`-n`** argument to prevent actually writing or
committing anything:

```text
$ bin/changelog --amend --dry-run
create changelogs/unreleased/feature-hey-dz.yml
---
title: Added an awesome new feature to GitLab
merge_request:
author:
217
type:
218 219 220 221

$ ls changelogs/unreleased/
```

222
##### `--git-username` or `-u`
223 224 225 226 227 228 229 230

Use the **`--git-username`** or **`-u`** argument to automatically fill in the
`author` value with your configured Git `user.name` value:

```text
$ git config user.name
Jane Doe

231
$ bin/changelog -u 'Hey DZ, I added a feature to GitLab!'
232 233 234 235 236
create changelogs/unreleased/feature-hey-dz.yml
---
title: Hey DZ, I added a feature to GitLab!
merge_request:
author: Jane Doe
237 238 239 240 241 242 243 244 245 246 247 248 249 250 251
type:
```

##### `--type` or `-t`

Use the **`--type`** or **`-t`** argument to provide the `type` value:

```text
$ bin/changelog 'Hey DZ, I added a feature to GitLab!' -t added
create changelogs/unreleased/feature-hey-dz.yml
---
title: Hey DZ, I added a feature to GitLab!
merge_request:
author:
type: added
252 253
```

254
### History and Reasoning
255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289

Our `CHANGELOG` file was previously updated manually by each contributor that
felt their change warranted an entry. When two merge requests added their own
entries at the same spot in the list, it created a merge conflict in one as soon
as the other was merged. When we had dozens of merge requests fighting for the
same changelog entry location, this quickly became a major source of merge
conflicts and delays in development.

This led us to a [boring solution] of "add your entry in a random location in
the list." This actually worked pretty well as we got further along in each
monthly release cycle, but at the start of a new cycle, when a new version
section was added and there were fewer places to "randomly" add an entry, the
conflicts became a problem again until we had a sufficient number of entries.

On top of all this, it created an entirely different headache for [release managers]
when they cherry-picked a commit into a stable branch for a patch release. If
the commit included an entry in the `CHANGELOG`, it would include the entire
changelog for the latest version in `master`, so the release manager would have
to manually remove the later entries. They often would have had to do this
multiple times per patch release. This was compounded when we had to release
multiple patches at once due to a security issue.

We needed to automate all of this manual work. So we [started brainstorming].
After much discussion we settled on the current solution of one file per entry,
and then compiling the entries into the overall `CHANGELOG.md` file during the
[release process].

[boring solution]: https://about.gitlab.com/handbook/#boring-solutions
[release managers]: https://gitlab.com/gitlab-org/release-tools/blob/master/doc/release-manager.md
[started brainstorming]: https://gitlab.com/gitlab-org/gitlab-ce/issues/17826
[release process]: https://gitlab.com/gitlab-org/release-tools

---

[Return to Development documentation](README.md)