summaryrefslogtreecommitdiff
path: root/doc/development/changelog.md
diff options
context:
space:
mode:
authorRobert Speicher <rspeicher@gmail.com>2017-03-16 12:56:41 -0400
committerRobert Speicher <rspeicher@gmail.com>2017-03-16 12:56:41 -0400
commit05107a891a565aa8687d7727a9046324f124928c (patch)
tree1eacaeb05ab541cebf19916716be176f4bdbda8b /doc/development/changelog.md
parent8f92de7b636d46ae9969df2aa791bfb3833ebd4a (diff)
downloadgitlab-ce-05107a891a565aa8687d7727a9046324f124928c.tar.gz
Expand on the good changelog/bad changelog documentation examples
[ci skip]
Diffstat (limited to 'doc/development/changelog.md')
-rw-r--r--doc/development/changelog.md20
1 files changed, 20 insertions, 0 deletions
diff --git a/doc/development/changelog.md b/doc/development/changelog.md
index ff9a4fc4fec..ce39a379a0e 100644
--- a/doc/development/changelog.md
+++ b/doc/development/changelog.md
@@ -51,14 +51,34 @@ 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.
+
+The first example provides no context of where the change was made, or why, or
+how it benefits the user.
+
- **Bad:** Copy [some text] to clipboard.
- **Good:** Update the "Copy to clipboard" tooltip to indicate what's being
copied.
+
+Again, the first example is too vague and provides no context.
+
- **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.
+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).
+
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?