diff options
author | Rémy Coutable <remy@rymai.me> | 2017-03-16 17:42:34 +0000 |
---|---|---|
committer | Rémy Coutable <remy@rymai.me> | 2017-03-16 17:42:34 +0000 |
commit | fc1a192e801d8468d83302d8992feed051e88288 (patch) | |
tree | 78f903ea617ad29147413544530eef327f708ecf | |
parent | 890832653dcf63c530ee5dcbd6782461173369bf (diff) | |
parent | 05107a891a565aa8687d7727a9046324f124928c (diff) | |
download | gitlab-ce-fc1a192e801d8468d83302d8992feed051e88288.tar.gz |
Merge branch 'rs-expand-changelog-examples' into 'master'
Expand on the good changelog/bad changelog documentation examples
See merge request !10016
-rw-r--r-- | doc/development/changelog.md | 20 |
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? |