update to current master and fix conflictsissue-title-vue

4 files changed, 47 insertions, 5 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?
diff --git a/doc/development/frontend.md b/doc/development/frontend.md
index e7add17fe2d..50105a486d0 100644
--- a/doc/development/frontend.md
+++ b/doc/development/frontend.md
@@ -32,6 +32,28 @@ You can find the Frontend Architecture experts on the [team page][team-page].
 
 You can find documentation about the desired architecture for a new feature built with Vue.js in [here][vue-section].
 
+### Realtime
+
+When writing code for realtime features we have to keep a couple of things in mind:
+1. Do not overload the server with requests.
+1. It should feel realtime.
+
+Thus, we must strike a balance between sending requests and the feeling of realtime.
+Use the following rules when creating realtime solutions.
+
+1. The server will tell you how much to poll by sending `Poll-Interval` in the header.
+Use that as your polling interval. This way it is easy for system administrators to change the
+polling rate.
+A `Poll-Interval: -1` means you should disable polling, and this must be implemented.
+1. A response with HTTP status `4XX` or `5XX` should disable polling as well.
+1. Use a common library for polling.
+1. Poll on active tabs only. Use a common library to find out which tab currently has eyes on it.
+Please use [Focus](https://gitlab.com/andrewn/focus). Specifically [Eyeballs Detector](https://gitlab.com/andrewn/focus/blob/master/lib/eyeballs-detector.js).
+1. Use regular polling intervals, do not use backoff polling, or jitter, as the interval will be
+controlled by the server.
+1. The backend code will most likely be using etags. You do not and should not check for status
+`304 Not Modified`. The browser will transform it for you.
+
 ### Vue
 
 For more complex frontend features, we recommend using Vue.js. It shares
diff --git a/doc/development/polling.md b/doc/development/polling.md
index a086aca6697..a7f2962acf0 100644
--- a/doc/development/polling.md
+++ b/doc/development/polling.md
@@ -27,13 +27,13 @@ Instead you should use polling mechanism with ETag caching in Redis.
 1. When a client makes a request we set the `ETag` response header to the value
    from Redis.
 1. The client caches the response (client-side caching) and sends the ETag as
-   the `If-None-Modified` header with every subsequent request for the same
+   the `If-None-Match` header with every subsequent request for the same
    resource.
-1. If the `If-None-Modified` header matches the current value in Redis we know
+1. If the `If-None-Match` header matches the current value in Redis we know
    that the resource did not change so we can send 304 response immediately,
    without querying the database at all. The client's browser will use the
    cached response.
-1. If the `If-None-Modified` header does not match the current value in Redis
+1. If the `If-None-Match` header does not match the current value in Redis
    we have to generate a new response, because the resource changed.
 
 For more information see:
diff --git a/doc/development/testing.md b/doc/development/testing.md
index 9b545d7f0f1..5ac7b8dadeb 100644
--- a/doc/development/testing.md
+++ b/doc/development/testing.md
@@ -35,8 +35,8 @@ GitLab uses [Karma] to run its [Jasmine] JavaScript specs. They can be run on
 the command line via `bundle exec karma`.
 
 - JavaScript tests live in `spec/javascripts/`, matching the folder structure of
-  `app/assets/javascripts/`: `app/assets/javascripts/behaviors/autosize.js.es6` has a corresponding
-  `spec/javascripts/behaviors/autosize_spec.js.es6` file.
+  `app/assets/javascripts/`: `app/assets/javascripts/behaviors/autosize.js` has a corresponding
+  `spec/javascripts/behaviors/autosize_spec.js` file.
 - Haml fixtures required for JavaScript tests live in
   `spec/javascripts/fixtures`. They should contain the bare minimum amount of
   markup necessary for the test.