Expand the changelog documentationrs-good-changelog-bad-changelog

Adds examples of what should and should not get a changelog entry, and
examples of good and bad entries.

[ci skip]

1 files changed, 65 insertions, 24 deletions

diff --git a/doc/development/changelog.md b/doc/development/changelog.md
index c71858c6a24..ff9a4fc4fec 100644
--- a/doc/development/changelog.md
+++ b/doc/development/changelog.md
@@ -1,7 +1,7 @@
-# Generate a changelog entry
+# Changelog entries
 
-This guide contains instructions for generating a changelog entry data file, as
-well as information and history about our changelog process.
+This guide contains instructions for when and how to generate a changelog entry
+file, as well as information and history about our changelog process.
 
 ## Overview
 
@@ -19,19 +19,51 @@ author: Ozzy Osbourne
 
 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
-contributors. Both are optional.
+contributors. **Both are optional**.
 
 Community contributors and core team members are encouraged to add their name to
-the `author` field. GitLab team members should not.
-
-If you're working on the GitLab EE repository, the entry will be added to
-`changelogs/unreleased-ee/` instead.
+the `author` field. GitLab team members **should not**.
 
 [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
 
-## Instructions
+## 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.
+- **Bad:** Copy [some text] to clipboard.
+- **Good:** Update the "Copy to clipboard" tooltip to indicate what's being
+  copied.
+- **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.
+
+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
 
 A `bin/changelog` script is available to generate the changelog entry file
 automatically.
@@ -55,19 +87,28 @@ title: Hey DZ, I added a feature to GitLab!
 merge_request:
 author:
 ```
+If you're working on the GitLab EE repository, the entry will be added to
+`changelogs/unreleased-ee/` instead.
+
+#### Arguments
 
-### Arguments
+| 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 |
+| [`--help`]          | `-h`      | Print help message                            |
 
-| Argument          | Shorthand | Purpose                                       |
-| ----------------- | --------- | --------------------------------------------- |
-| `--amend`         |           | Amend the previous commit                     |
-| `--force`         | `-f`      | Overwrite an existing entry                   |
-| `--merge-request` | `-m`      | Merge Request ID                              |
-| `--dry-run`       | `-n`      | Don't actually write anything, just print     |
-| `--git-username`  | `-u`      | Use Git user.name configuration as the author |
-| `--help`          | `-h`      | Print help message                            |
+[`--amend`]: #-amend
+[`--force`]: #-force-or-f
+[`--merge-request`]: #-merge-request-or-m
+[`--dry-run`]: #-dry-run-or-n
+[`--git-username`]: #-git-username-or-u
+[`--help`]: #-help
 
-#### `--amend`
+##### `--amend`
 
 You can pass the **`--amend`** argument to automatically stage the generated
 file and amend it to the previous commit.
@@ -88,7 +129,7 @@ merge_request:
 author:
 ```
 
-#### `--force` or `-f`
+##### `--force` or `-f`
 
 Use **`--force`** or **`-f`** to overwrite an existing changelog entry if it
 already exists.
@@ -105,7 +146,7 @@ merge_request: 1983
 author:
 ```
 
-#### `--merge-request` or `-m`
+##### `--merge-request` or `-m`
 
 Use the **`--merge-request`** or **`-m`** argument to provide the
 `merge_request` value:
@@ -119,7 +160,7 @@ merge_request: 1983
 author:
 ```
 
-#### `--dry-run` or `-n`
+##### `--dry-run` or `-n`
 
 Use the **`--dry-run`** or **`-n`** argument to prevent actually writing or
 committing anything:
@@ -135,7 +176,7 @@ author:
 $ ls changelogs/unreleased/
 ```
 
-#### `--git-username` or `-u`
+##### `--git-username` or `-u`
 
 Use the **`--git-username`** or **`-u`** argument to automatically fill in the
 `author` value with your configured Git `user.name` value:
@@ -152,7 +193,7 @@ merge_request:
 author: Jane Doe
 ```
 
-## History and Reasoning
+### History and Reasoning
 
 Our `CHANGELOG` file was previously updated manually by each contributor that
 felt their change warranted an entry. When two merge requests added their own