12 files changed, 1315 insertions, 303 deletions

diff --git a/doc/development/fe_guide/droplab/droplab.md b/doc/development/fe_guide/droplab/droplab.md
new file mode 100644
index 00000000000..112ff3419d9
--- /dev/null
+++ b/doc/development/fe_guide/droplab/droplab.md
@@ -0,0 +1,258 @@
+# DropLab
+
+A generic dropdown for all of your custom dropdown needs.
+
+## Usage
+
+DropLab can be used by simply adding a `data-dropdown-trigger` HTML attribute.
+This attribute allows us to find the "trigger" _(toggle)_ for the dropdown,
+whether that is a button, link or input.
+
+The value of the `data-dropdown-trigger` should be a CSS selector that
+DropLab can use to find the trigger's dropdown list.
+
+You should also add the `data-dropdown` attribute to declare the dropdown list.
+The value is irrelevant.
+
+The DropLab class has no side effects, so you must always call `.init` when
+the DOM is ready. `DropLab.prototype.init` takes the same arguments as `DropLab.prototype.addHook`.
+If you do not provide any arguments, it will globally query and instantiate all droplab compatible dropdowns.
+
+```html
+<a href="#" data-dropdown-trigger="#list">Toggle</a>
+
+<ul id="list" data-dropdown>
+  <!-- ... -->
+<ul>
+```
+```js
+const droplab = new DropLab();
+droplab.init();
+```
+
+As you can see, we have a "Toggle" link, that is declared as a trigger.
+It provides a selector to find the dropdown list it should control.
+
+### Static data
+
+You can add static list items.
+
+```html
+<a href="#" data-dropdown-trigger="#list">Toggle</a>
+
+<ul id="list" data-dropdown>
+  <li>Static value 1</li>
+  <li>Static value 2</li>
+<ul>
+```
+```js
+const droplab = new DropLab();
+droplab.init();
+```
+
+### Explicit instantiation
+
+You can pass the trigger and list elements as constructor arguments to return
+a non-global instance of DropLab using the `DropLab.prototype.init` method.
+
+```html
+<a href="#" id="trigger" data-dropdown-trigger="#list">Toggle</a>
+
+<ul id="list" data-dropdown>
+  <!-- ... -->
+<ul>
+```
+```js
+const trigger = document.getElementById('trigger');
+const list = document.getElementById('list');
+
+const droplab = new DropLab();
+droplab.init(trigger, list);
+```
+
+You can also add hooks to an existing DropLab instance using `DropLab.prototype.addHook`.
+
+```html
+<a href="#" data-dropdown-trigger="#auto-dropdown">Toggle</a>
+<ul id="auto-dropdown" data-dropdown><!-- ... --><ul>
+
+<a href="#" id="trigger" data-dropdown-trigger="#list">Toggle</a>
+<ul id="list" data-dropdown><!-- ... --><ul>
+```
+```js
+const droplab = new DropLab();
+
+droplab.init();
+
+const trigger = document.getElementById('trigger');
+const list = document.getElementById('list');
+
+droplab.addHook(trigger, list);
+```
+
+
+### Dynamic data
+
+Adding `data-dynamic` to your dropdown element will enable dynamic list rendering.
+
+You can template a list item using the keys of the data object provided.
+Use the handlebars syntax `{{ value }}` to HTML escape the value.
+Use the `<%= value %>` syntax to simply interpolate the value.
+Use the `<%= value %>` syntax to evaluate the value.
+
+Passing an array of objects to `DropLab.prototype.addData` will render that data
+for all `data-dynamic` dropdown lists tracked by that DropLab instance.
+
+```html
+<a href="#" data-dropdown-trigger="#list">Toggle</a>
+
+<ul id="list" data-dropdown data-dynamic>
+  <li><a href="#" data-id="{{id}}">{{text}}</a></li>
+</ul>
+```
+```js
+const droplab = new DropLab();
+
+droplab.init().addData([{
+  id: 0,
+  text: 'Jacob',
+}, {
+  id: 1,
+  text: 'Jeff',
+}]);
+```
+
+Alternatively, you can specify a specific dropdown to add this data to but passing
+the data as the second argument and and the `id` of the trigger element as the first argument.
+
+```html
+<a href="#" data-dropdown-trigger="#list" id="trigger">Toggle</a>
+
+<ul id="list" data-dropdown data-dynamic>
+  <li><a href="#" data-id="{{id}}">{{text}}</a></li>
+</ul>
+```
+```js
+const droplab = new DropLab();
+
+droplab.init().addData('trigger', [{
+  id: 0,
+  text: 'Jacob',
+}, {
+  id: 1,
+  text: 'Jeff',
+}]);
+```
+
+This allows you to mix static and dynamic content with ease, even with one trigger.
+
+Note the use of scoping regarding the `data-dropdown` attribute to capture both
+dropdown lists, one of which is dynamic.
+
+```html
+<input id="trigger" data-dropdown-trigger="#list">
+<div id="list" data-dropdown>
+  <ul>
+    <li><a href="#">Static item 1</a></li>
+    <li><a href="#">Static item 2</a></li>
+  </ul>
+  <ul data-dynamic>
+    <li><a href="#" data-id="{{id}}">{{text}}</a></li>
+  </ul>
+</div>
+```
+```js
+const droplab = new DropLab();
+
+droplab.init().addData('trigger', [{
+  id: 0,
+  text: 'Jacob',
+}, {
+  id: 1,
+  text: 'Jeff',
+}]);
+```
+
+## Internal selectors
+
+DropLab adds some CSS classes to help lower the barrier to integration.
+
+For example,
+
+* The `droplab-item-selected` css class is added to items that have been selected
+either by a mouse click or by enter key selection.
+* The `droplab-item-active` css class is added to items that have been selected
+using arrow key navigation.
+* You can add the `droplab-item-ignore` css class to any item that you do not want to be selectable. For example,
+an `<li class="divider"></li>` list divider element that should not be interactive.
+
+## Internal events
+
+DropLab uses some custom events to help lower the barrier to integration.
+
+For example,
+
+* The `click.dl` event is fired when an `li` list item has been clicked. It is also
+fired when a list item has been selected with the keyboard. It is also fired when a
+`HookButton` button is clicked (a registered `button` tag or `a` tag trigger).
+* The `input.dl` event is fired when a `HookInput` (a registered `input` tag trigger) triggers an `input` event.
+* The `mousedown.dl` event is fired when a `HookInput` triggers a `mousedown` event.
+* The `keyup.dl` event is fired when a `HookInput` triggers a `keyup` event.
+* The `keydown.dl` event is fired when a `HookInput` triggers a `keydown` event.
+
+These custom events add a `detail` object to the vanilla `Event` object that provides some potentially useful data.
+
+## Plugins
+
+Plugins are objects that are registered to be executed when a hook is added (when a droplab trigger and dropdown are instantiated).
+
+If no modules API is detected, the library will fall back as it does with `window.DropLab` and will add `window.DropLab.plugins.PluginName`.
+
+### Usage
+
+To use plugins, you can pass them in an array as the third argument of `DropLab.prototype.init` or `DropLab.prototype.addHook`.
+Some plugins require configuration values, the config object can be passed as the fourth argument.
+
+```html
+<a href="#" id="trigger" data-dropdown-trigger="#list">Toggle</a>
+<ul id="list" data-dropdown><!-- ... --><ul>
+```
+```js
+const droplab = new DropLab();
+
+const trigger = document.getElementById('trigger');
+const list = document.getElementById('list');
+
+droplab.init(trigger, list, [droplabAjax], {
+  droplabAjax: {
+    endpoint: '/some-endpoint',
+    method: 'setData',
+  },
+});
+```
+
+### Documentation
+
+* [Ajax plugin](plugins/ajax.md)
+* [Filter plugin](plugins/filter.md)
+* [InputSetter plugin](plugins/input_setter.md)
+
+### Development
+
+When plugins are initialised for a droplab trigger+dropdown, DropLab will
+call the plugins `init` function, so this must be implemented in the plugin.
+
+```js
+class MyPlugin {
+  static init() {
+    this.someProp = 'someProp';
+    this.someMethod();
+  }
+
+  static someMethod() {
+    this.otherProp = 'otherProp';
+  }
+}
+
+export default MyPlugin;
+```
diff --git a/doc/development/fe_guide/droplab/plugins/ajax.md b/doc/development/fe_guide/droplab/plugins/ajax.md
new file mode 100644
index 00000000000..9c7e56fa448
--- /dev/null
+++ b/doc/development/fe_guide/droplab/plugins/ajax.md
@@ -0,0 +1,37 @@
+# Ajax
+
+`Ajax` is a droplab plugin that allows for retrieving and rendering list data from a server.
+
+## Usage
+
+Add the `Ajax` object to the plugins array of a `DropLab.prototype.init` or `DropLab.prototype.addHook` call.
+
+`Ajax` requires 2 config values, the `endpoint` and `method`.
+
+* `endpoint` should be a URL to the request endpoint.
+* `method` should be `setData` or `addData`.
+* `setData` completely replaces the dropdown with the response data.
+* `addData` appends the response data to the current dropdown list.
+
+```html
+<a href="#" id="trigger" data-dropdown-trigger="#list">Toggle</a>
+<ul id="list" data-dropdown><!-- ... --><ul>
+```
+```js
+  const droplab = new DropLab();
+
+  const trigger = document.getElementById('trigger');
+  const list = document.getElementById('list');
+
+  droplab.addHook(trigger, list, [Ajax], {
+    Ajax: {
+      endpoint: '/some-endpoint',
+      method: 'setData',
+    },
+  });
+```
+
+Optionally you can set `loadingTemplate` to a HTML string. This HTML string will
+replace the dropdown list whilst the request is pending.
+
+Additionally, you can set `onError` to a function to catch any XHR errors.
diff --git a/doc/development/fe_guide/droplab/plugins/filter.md b/doc/development/fe_guide/droplab/plugins/filter.md
new file mode 100644
index 00000000000..0853ea4d320
--- /dev/null
+++ b/doc/development/fe_guide/droplab/plugins/filter.md
@@ -0,0 +1,45 @@
+# Filter
+
+`Filter` is a plugin that allows for filtering data that has been added
+to the dropdown using a simple fuzzy string search of an input value.
+
+## Usage
+
+Add the `Filter` object to the plugins array of a `DropLab.prototype.init` or `DropLab.prototype.addHook` call.
+
+* `Filter` requires a config value for `template`.
+* `template` should be the key of the objects within your data array that you want to compare
+to the user input string, for filtering.
+
+```html
+<input href="#" id="trigger" data-dropdown-trigger="#list">
+<ul id="list" data-dropdown data-dynamic>
+  <li><a href="#" data-id="{{id}}">{{text}}</a></li>
+<ul>
+```
+```js
+  const droplab = new DropLab();
+
+  const trigger = document.getElementById('trigger');
+  const list = document.getElementById('list');
+
+  droplab.init(trigger, list, [Filter], {
+    Filter: {
+      template: 'text',
+    },
+  });
+
+  droplab.addData('trigger', [{
+    id: 0,
+    text: 'Jacob',
+  }, {
+    id: 1,
+    text: 'Jeff',
+  }]);
+```
+
+Above, the input string will be compared against the `test` key of the passed data objects.
+
+Optionally you can set `filterFunction` to a function. This function will be used instead
+of `Filter`'s built in string search. `filterFunction` is passed 2 arguments, the first
+is one of the data objects, the second is the current input value.
diff --git a/doc/development/fe_guide/droplab/plugins/input_setter.md b/doc/development/fe_guide/droplab/plugins/input_setter.md
new file mode 100644
index 00000000000..a549603c20d
--- /dev/null
+++ b/doc/development/fe_guide/droplab/plugins/input_setter.md
@@ -0,0 +1,60 @@
+# InputSetter
+
+`InputSetter` is a plugin that allows for udating DOM out of the scope of droplab when a list item is clicked.
+
+## Usage
+
+Add the `InputSetter` object to the plugins array of a `DropLab.prototype.init` or `DropLab.prototype.addHook` call.
+
+* `InputSetter` requires a config value for `input` and `valueAttribute`.
+* `input` should be the DOM element that you want to manipulate.
+* `valueAttribute` should be a string that is the name of an attribute on your list items that is used to get the value
+to update the `input` element with.
+
+You can also set the `InputSetter` config to an array of objects, which will allow you to update multiple elements.
+
+
+```html
+<input id="input" value="">
+<div id="div" data-selected-id=""></div>
+
+<input href="#" id="trigger" data-dropdown-trigger="#list">
+<ul id="list" data-dropdown data-dynamic>
+  <li><a href="#" data-id="{{id}}">{{text}}</a></li>
+<ul>
+```
+```js
+  const droplab = new DropLab();
+
+  const trigger = document.getElementById('trigger');
+  const list = document.getElementById('list');
+
+  const input = document.getElementById('input');
+  const div = document.getElementById('div');
+
+  droplab.init(trigger, list, [InputSetter], {
+    InputSetter: [{
+      input: input,
+      valueAttribute: 'data-id',
+    } {
+      input: div,
+      valueAttribute: 'data-id',
+      inputAttribute: 'data-selected-id',
+    }],
+  });
+
+  droplab.addData('trigger', [{
+    id: 0,
+    text: 'Jacob',
+  }, {
+    id: 1,
+    text: 'Jeff',
+  }]);
+```
+
+Above, if the second list item was clicked, it would update the `#input` element
+to have a `value` of `1`, it would also update the `#div` element's `data-selected-id` to `1`.
+
+Optionally you can set `inputAttribute` to a string that is the name of an attribute on your `input` element that you want to update.
+If you do not provide an `inputAttribute`, `InputSetter` will update the `value` of the `input` element if it is an `INPUT` element,
+or the `textContent` of the `input` element if it is not an `INPUT` element.
diff --git a/doc/development/fe_guide/img/boards_diagram.png b/doc/development/fe_guide/img/boards_diagram.png
new file mode 100644
index 00000000000..7a2cf972fd0
--- /dev/null
+++ b/doc/development/fe_guide/img/boards_diagram.png
diff --git a/doc/development/fe_guide/img/testing_triangle.png b/doc/development/fe_guide/img/testing_triangle.png
new file mode 100644
index 00000000000..7a9a848c2ee
--- /dev/null
+++ b/doc/development/fe_guide/img/testing_triangle.png
diff --git a/doc/development/fe_guide/img/vue_arch.png b/doc/development/fe_guide/img/vue_arch.png
new file mode 100644
index 00000000000..a67706c7c1e
--- /dev/null
+++ b/doc/development/fe_guide/img/vue_arch.png
diff --git a/doc/development/fe_guide/index.md b/doc/development/fe_guide/index.md
index f963bffde37..64bcb4a0257 100644
--- a/doc/development/fe_guide/index.md
+++ b/doc/development/fe_guide/index.md
@@ -27,6 +27,55 @@ For our currently-supported browsers, see our [requirements][requirements].
 
 ---
 
+## Development Process
+
+When you are assigned an issue please follow the next steps:
+
+### Divide a big feature into small Merge Requests
+1. Big Merge Request are painful to review. In order to make this process easier we
+must break a big feature into smaller ones and create a Merge Request for each step.
+1. First step is to create a branch from `master`, let's call it `new-feature`. This branch
+will be the recipient of all the smaller Merge Requests. Only this one will be merged to master.
+1. Don't do any work on this one, let's keep it synced with master.
+1. Create a new branch from `new-feature`, let's call it `new-feature-step-1`. We advise you
+to clearly identify which step the branch represents.
+1. Do the first part of the modifications in this branch. The target branch of this Merge Request
+should be `new-feature`.
+1. Once `new-feature-step-1` gets merged into `new-feature` we can continue our work. Create a new
+branch from `new-feature`, let's call it `new-feature-step-2` and repeat the process done before.
+
+```shell
+master
+└─ new-feature
+   ├─ new-feature-step-1
+   ├─ new-feature-step-2
+   └─ new-feature-step-3
+```
+
+**Tips**
+- Make sure `new-feature` branch is always synced with `master`: merge master frequently.
+- Do the same for the feature branch you have opened. This can be accomplished by merging `master` into `new-feature` and `new-feature` into `new-feature-step-*`
+- Avoid rewriting history.
+
+### Share your work early
+1. Before writing code guarantee your vision of the architecture is aligned with
+GitLab's architecture.
+1. Add a diagram to the issue and ask a Frontend Architecture about it.
+
+  ![Diagram of Issue Boards Architecture](img/boards_diagram.png)
+
+1. Don't take more than one week between starting work on a feature and
+sharing a Merge Request with a reviewer or a maintainer.
+
+### Vue features
+1. Follow the steps in [Vue.js Best Practices](vue.md)
+1. Follow the style guide.
+1. Only a handful of people are allowed to merge Vue related features.
+Reach out to one of Vue experts early in this process.
+
+
+---
+
 ## [Architecture](architecture.md)
 How we go about making fundamental design decisions in GitLab's frontend team
 or make changes to our frontend development guidelines.
@@ -90,3 +139,13 @@ Our accessibility standards and resources.
 [scss-lint]: https://github.com/brigade/scss-lint
 [install]: ../../install/installation.md#4-node
 [requirements]: ../../install/requirements.md#supported-web-browsers
+
+---
+
+## [DropLab](droplab/droplab.md)
+Our internal `DropLab` dropdown library.
+
+* [DropLab](droplab/droplab.md)
+* [Ajax plugin](droplab/plugins/ajax.md)
+* [Filter plugin](droplab/plugins/filter.md)
+* [InputSetter plugin](droplab/plugins/input_setter.md)
diff --git a/doc/development/fe_guide/performance.md b/doc/development/fe_guide/performance.md
index 9437a5f7a6e..2ddcbe13afa 100644
--- a/doc/development/fe_guide/performance.md
+++ b/doc/development/fe_guide/performance.md
@@ -12,8 +12,8 @@ Thus, we must strike a balance between sending requests and the feeling of realt
 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.
+Use that as your polling interval. This way it is [easy for system administrators to change the
+polling rate](../../administration/polling.md).
 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.
@@ -48,8 +48,8 @@ Steps to split page-specific JavaScript from the main `main.js`:
 
 ```haml
 - content_for :page_specific_javascripts do
-  = page_specific_javascript_bundle_tag('lib_chart')
-  = page_specific_javascript_bundle_tag('graphs')
+  = webpack_bundle_tag 'lib_chart'
+  = webpack_bundle_tag 'graphs'
 ```
 
 The above loads `chart.js` and `graphs_bundle.js` for this page only. `chart.js`
diff --git a/doc/development/fe_guide/style_guide_js.md b/doc/development/fe_guide/style_guide_js.md
index abd241c0bc8..d2d89517241 100644
--- a/doc/development/fe_guide/style_guide_js.md
+++ b/doc/development/fe_guide/style_guide_js.md
@@ -11,401 +11,483 @@ See [our current .eslintrc][eslintrc] for specific rules and patterns.
 
 #### ESlint
 
-- **Never** disable eslint rules unless you have a good reason.  You may see a lot of legacy files with `/* eslint-disable some-rule, some-other-rule */` at the top, but legacy files are a special case.  Any time you develop a new feature or refactor an existing one, you should abide by the eslint rules.
-
-- **Never Ever EVER** disable eslint globally for a file
+1. **Never** disable eslint rules unless you have a good reason.  
+You may see a lot of legacy files with `/* eslint-disable some-rule, some-other-rule */`
+at the top, but legacy files are a special case.  Any time you develop a new feature or
+refactor an existing one, you should abide by the eslint rules.
 
+1. **Never Ever EVER** disable eslint globally for a file
   ```javascript
-  // bad
-  /* eslint-disable */
+    // bad
+    /* eslint-disable */
 
-  // better
-  /* eslint-disable some-rule, some-other-rule */
+    // better
+    /* eslint-disable some-rule, some-other-rule */
 
-  // best
-  // nothing :)
+    // best
+    // nothing :)
   ```
 
-- If you do need to disable a rule for a single violation, try to do it as locally as possible
-
+1. If you do need to disable a rule for a single violation, try to do it as locally as possible
   ```javascript
-  // bad
-  /* eslint-disable no-new */
+    // bad
+    /* eslint-disable no-new */
 
-  import Foo from 'foo';
+    import Foo from 'foo';
 
-  new Foo();
+    new Foo();
 
-  // better
-  import Foo from 'foo';
+    // better
+    import Foo from 'foo';
 
-  // eslint-disable-next-line no-new
-  new Foo();
+    // eslint-disable-next-line no-new
+    new Foo();
   ```
+1. There are few rules that we need to disable due to technical debt. Which are:
+  1. [no-new][eslint-new]
+  1. [class-methods-use-this][eslint-this]
 
-- When they are needed _always_ place ESlint directive comment blocks on the first line of a script, followed by any global declarations, then a blank newline prior to any imports or code.
-
+1. When they are needed _always_ place ESlint directive comment blocks on the first line of a script,
+followed by any global declarations, then a blank newline prior to any imports or code.
   ```javascript
-  // bad
-  /* global Foo */
-  /* eslint-disable no-new */
-  import Bar from './bar';
+    // bad
+    /* global Foo */
+    /* eslint-disable no-new */
+    import Bar from './bar';
 
-  // good
-  /* eslint-disable no-new */
-  /* global Foo */
+    // good
+    /* eslint-disable no-new */
+    /* global Foo */
 
-  import Bar from './bar';
+    import Bar from './bar';
   ```
 
-- **Never** disable the `no-undef` rule.  Declare globals with `/* global Foo */` instead.
+1. **Never** disable the `no-undef` rule. Declare globals with `/* global Foo */` instead.
+
+1. When declaring multiple globals, always use one `/* global [name] */` line per variable.
+  ```javascript
+    // bad
+    /* globals Flash, Cookies, jQuery */
 
-- When declaring multiple globals, always use one `/* global [name] */` line per variable.
+    // good
+    /* global Flash */
+    /* global Cookies */
+    /* global jQuery */
+  ```
 
+1. Use up to 3 parameters for a function or class. If you need more accept an Object instead.
   ```javascript
-  // bad
-  /* globals Flash, Cookies, jQuery */
+    // bad
+    fn(p1, p2, p3, p4) {}
 
-  // good
-  /* global Flash */
-  /* global Cookies */
-  /* global jQuery */
+    // good
+    fn(options) {}
   ```
 
 #### Modules, Imports, and Exports
-- Use ES module syntax to import modules
-
+1. Use ES module syntax to import modules
   ```javascript
-  // bad
-  require('foo');
+    // bad
+    require('foo');
 
-  // good
-  import Foo from 'foo';
+    // good
+    import Foo from 'foo';
 
-  // bad
-  module.exports = Foo;
+    // bad
+    module.exports = Foo;
 
-  // good
-  export default Foo;
+    // good
+    export default Foo;
   ```
 
-- Relative paths
-
-  Unless you are writing a test, always reference other scripts using relative paths instead of `~`
+1. Relative paths: Unless you are writing a test, always reference other scripts using
+relative paths instead of `~`
+  * In **app/assets/javascripts**:
 
-  In **app/assets/javascripts**:
-  ```javascript
-  // bad
-  import Foo from '~/foo'
-
-  // good
-  import Foo from '../foo';
-  ```
+    ```javascript
+      // bad
+      import Foo from '~/foo'
 
-  In **spec/javascripts**:
-  ```javascript
-  // bad
-  import Foo from '../../app/assets/javascripts/foo'
+      // good
+      import Foo from '../foo';
+    ```
+  * In **spec/javascripts**:
 
-  // good
-  import Foo from '~/foo';
-  ```
+    ```javascript
+      // bad
+      import Foo from '../../app/assets/javascripts/foo'
 
-- Avoid using IIFE. Although we have a lot of examples of files which wrap their contents in IIFEs (immediately-invoked function expressions), this is no longer necessary after the transition from Sprockets to webpack. Do not use them anymore and feel free to remove them when refactoring legacy code.
+      // good
+      import Foo from '~/foo';
+    ```
 
-- Avoid adding to the global namespace.
+1. Avoid using IIFE. Although we have a lot of examples of files which wrap their
+contents in IIFEs (immediately-invoked function expressions),
+this is no longer necessary after the transition from Sprockets to webpack.
+Do not use them anymore and feel free to remove them when refactoring legacy code.
 
+1. Avoid adding to the global namespace.
   ```javascript
-  // bad
-  window.MyClass = class { /* ... */ };
+    // bad
+    window.MyClass = class { /* ... */ };
 
-  // good
-  export default class MyClass { /* ... */ }
+    // good
+    export default class MyClass { /* ... */ }
   ```
 
-- Side effects are forbidden in any script which contains exports
-
+1. Side effects are forbidden in any script which contains exports
   ```javascript
-  // bad
-  export default class MyClass { /* ... */ }
+    // bad
+    export default class MyClass { /* ... */ }
 
-  document.addEventListener("DOMContentLoaded", function(event) {
-    new MyClass();
-  }
+    document.addEventListener("DOMContentLoaded", function(event) {
+      new MyClass();
+    }
   ```
 
 
 #### Data Mutation and Pure functions
-- Strive to write many small pure functions, and minimize where mutations occur.
-
+1. Strive to write many small pure functions, and minimize where mutations occur.
   ```javascript
-  // bad
-  const values = {foo: 1};
+    // bad
+    const values = {foo: 1};
 
-  function impureFunction(items) {
-    const bar = 1;
+    function impureFunction(items) {
+      const bar = 1;
 
-    items.foo = items.a * bar + 2;
+      items.foo = items.a * bar + 2;
 
-    return items.a;
-  }
+      return items.a;
+    }
 
-  const c = impureFunction(values);
+    const c = impureFunction(values);
 
-  // good
-  var values = {foo: 1};
+    // good
+    var values = {foo: 1};
 
-  function pureFunction (foo) {
-    var bar = 1;
+    function pureFunction (foo) {
+      var bar = 1;
 
-    foo = foo * bar + 2;
+      foo = foo * bar + 2;
 
-    return foo;
-  }
+      return foo;
+    }
 
-  var c = pureFunction(values.foo);
+    var c = pureFunction(values.foo);
   ```
 
-- Avoid constructors with side-effects
+1. Avoid constructors with side-effects
 
+1. Prefer `.map`, `.reduce` or `.filter` over `.forEach`
+A forEach will cause side effects, it will be mutating the array being iterated. Prefer using `.map`,
+`.reduce` or `.filter`
+  ```javascript
+    const users = [ { name: 'Foo' }, { name: 'Bar' } ];
 
-#### Parse Strings into Numbers
-- `parseInt()` is preferable over `Number()` or `+`
+    // bad
+    users.forEach((user, index) => {
+      user.id = index;
+    });
 
+    // good
+    const usersWithId = users.map((user, index) => {
+      return Object.assign({}, user, { id: index });
+    });
+  ```
+
+#### Parse Strings into Numbers
+1. `parseInt()` is preferable over `Number()` or `+`
   ```javascript
-  // bad
-  +'10' // 10
+    // bad
+    +'10' // 10
 
-  // good
-  Number('10') // 10
+    // good
+    Number('10') // 10
 
-  // better
-  parseInt('10', 10);
+    // better
+    parseInt('10', 10);
   ```
 
+#### CSS classes used for JavaScript
+1. If the class is being used in Javascript it needs to be prepend with `js-`
+  ```html
+    // bad
+    <button class="add-user">
+      Add User
+    </button>
+
+    // good
+    <button class="js-add-user">
+      Add User
+    </button>
+  ```
 
 ### Vue.js
 
-
 #### Basic Rules
-- Only include one Vue.js component per file.
-- Export components as plain objects:
-
+1. The service has it's own file
+1. The store has it's own file
+1. Use a function in the bundle file to instantiate the Vue component:
   ```javascript
-  export default {
-    template: `<h1>I'm a component</h1>
-  }
+    // bad
+    class {
+      init() {
+        new Component({})
+      }
+    }
+
+    // good
+    document.addEventListener('DOMContentLoaded', () => new Vue({
+      el: '#element',
+      components: {
+        componentName
+      },
+      render: createElement => createElement('component-name'),
+    }));
   ```
 
-#### Naming
-- **Extensions**: Use `.vue` extension for Vue components.
-- **Reference Naming**: Use PascalCase for Vue components and camelCase for their instances:
+1. Don not use a singleton for the service or the store
   ```javascript
-  // bad
-  import cardBoard from 'cardBoard';
+    // bad
+    class Store {
+      constructor() {
+        if (!this.prototype.singleton) {
+          // do something
+        }
+      }
+    }
 
-  // good
-  import CardBoard from 'cardBoard'
+    // good
+    class Store {
+      constructor() {
+        // do something
+      }
+    }
+  ```
 
-  // bad
-  components: {
-    CardBoard: CardBoard
-  };
+#### Naming
+1. **Extensions**: Use `.vue` extension for Vue components.
+1. **Reference Naming**: Use camelCase for their instances:
+  ```javascript
+    // good
+    import cardBoard from 'cardBoard'
 
-  // good
-  components: {
-    cardBoard: CardBoard
-  };
+    components: {
+      cardBoard:
+    };
   ```
-- **Props Naming:**
-- Avoid using DOM component prop names.
-- Use kebab-case instead of camelCase to provide props in templates.
 
+1. **Props Naming:**  Avoid using DOM component prop names.
+1. **Props Naming:** Use kebab-case instead of camelCase to provide props in templates.
   ```javascript
-  // bad
-  <component class="btn">
+    // bad
+    <component class="btn">
 
-  // good
-  <component css-class="btn">
+    // good
+    <component css-class="btn">
 
-  // bad
-  <component myProp="prop" />
+    // bad
+    <component myProp="prop" />
 
-  // good
-  <component my-prop="prop" />
-```
+    // good
+    <component my-prop="prop" />
+  ```
 
 #### Alignment
-- Follow these alignment styles for the template method:
-
+1. Follow these alignment styles for the template method:
   ```javascript
-  // bad
-  <component v-if="bar"
-      param="baz" />
-
-  // good
-  <component
-    v-if="bar"
-    param="baz"
-  />
-
-  // if props fit in one line then keep it on the same line
-  <component bar="bar" />
+    // bad
+    <component v-if="bar"
+        param="baz" />
+
+    <button class="btn">Click me</button>
+
+    // good
+    <component
+      v-if="bar"
+      param="baz"
+    />
+
+    <button class="btn">
+      Click me
+    </button>
+
+    // if props fit in one line then keep it on the same line
+    <component bar="bar" />
   ```
 
 #### Quotes
-- Always use double quotes `"` inside templates and single quotes `'` for all other JS.
-
+1. Always use double quotes `"` inside templates and single quotes `'` for all other JS.
   ```javascript
-  // bad
-  template: `
-    <button :class='style'>Button</button>
-  `
-
-  // good
-  template: `
-    <button :class="style">Button</button>
-  `
+    // bad
+    template: `
+      <button :class='style'>Button</button>
+    `
+
+    // good
+    template: `
+      <button :class="style">Button</button>
+    `
   ```
 
 #### Props
-- Props should be declared as an object
-
+1. Props should be declared as an object
   ```javascript
-  // bad
-  props: ['foo']
-
-  // good
-  props: {
-    foo: {
-      type: String,
-      required: false,
-      default: 'bar'
+    // bad
+    props: ['foo']
+
+    // good
+    props: {
+      foo: {
+        type: String,
+        required: false,
+        default: 'bar'
+      }
     }
-  }
   ```
 
-- Required key should always be provided when declaring a prop
-
+1. Required key should always be provided when declaring a prop
   ```javascript
-  // bad
-  props: {
-    foo: {
-      type: String,
+    // bad
+    props: {
+      foo: {
+        type: String,
+      }
     }
-  }
-
-  // good
-  props: {
-    foo: {
-      type: String,
-      required: false,
-      default: 'bar'
+
+    // good
+    props: {
+      foo: {
+        type: String,
+        required: false,
+        default: 'bar'
+      }
     }
-  }
   ```
 
-- Default key should always be provided if the prop is not required:
-
+1. Default key should always be provided if the prop is not required:
   ```javascript
-  // bad
-  props: {
-    foo: {
-      type: String,
-      required: false,
+    // bad
+    props: {
+      foo: {
+        type: String,
+        required: false,
+      }
     }
-  }
-
-  // good
-  props: {
-    foo: {
-      type: String,
-      required: false,
-      default: 'bar'
+
+    // good
+    props: {
+      foo: {
+        type: String,
+        required: false,
+        default: 'bar'
+      }
     }
-  }
 
-  // good
-  props: {
-    foo: {
-      type: String,
-      required: true
+    // good
+    props: {
+      foo: {
+        type: String,
+        required: true
+      }
     }
-  }
   ```
 
 #### Data
-- `data` method should always be a function
+1. `data` method should always be a function
 
   ```javascript
-  // bad
-  data: {
-    foo: 'foo'
-  }
-
-  // good
-  data() {
-    return {
+    // bad
+    data: {
       foo: 'foo'
-    };
-  }
+    }
+
+    // good
+    data() {
+      return {
+        foo: 'foo'
+      };
+    }
   ```
 
 #### Directives
 
-- Shorthand `@` is preferable over `v-on`
-
+1. Shorthand `@` is preferable over `v-on`
   ```javascript
-  // bad
-  <component v-on:click="eventHandler"/>
+    // bad
+    <component v-on:click="eventHandler"/>
 
 
-  // good
-  <component @click="eventHandler"/>
+    // good
+    <component @click="eventHandler"/>
   ```
 
-- Shorthand `:` is preferable over `v-bind`
-
+1. Shorthand `:` is preferable over `v-bind`
   ```javascript
-  // bad
-  <component v-bind:class="btn"/>
+    // bad
+    <component v-bind:class="btn"/>
 
 
-  // good
-  <component :class="btn"/>
+    // good
+    <component :class="btn"/>
   ```
 
 #### Closing tags
-- Prefer self closing component tags
-
+1. Prefer self closing component tags
   ```javascript
-  // bad
-  <component></component>
+    // bad
+    <component></component>
 
-  // good
-  <component />
+    // good
+    <component />
   ```
 
 #### Ordering
-- Order for a Vue Component:
+1. Order for a Vue Component:
   1. `name`
-  2. `props`
-  3. `data`
-  4. `components`
-  5. `computedProps`
-  6. `methods`
-  7. lifecycle methods
-    1. `beforeCreate`
-    2. `created`
-    3. `beforeMount`
-    4. `mounted`
-    5. `beforeUpdate`
-    6. `updated`
-    7. `activated`
-    8. `deactivated`
-    9. `beforeDestroy`
-    10. `destroyed`
-  8. `template`
+  1. `props`
+  1. `mixins`
+  1. `data`
+  1. `components`
+  1. `computedProps`
+  1. `methods`
+  1. `beforeCreate`
+  1. `created`
+  1. `beforeMount`
+  1. `mounted`
+  1. `beforeUpdate`
+  1. `updated`
+  1. `activated`
+  1. `deactivated`
+  1. `beforeDestroy`
+  1. `destroyed`
+
+#### Vue and Boostrap
+1. Tooltips: Do not rely on `has-tooltip` class name for vue components
+  ```javascript
+    // bad
+    <span class="has-tooltip">
+      Text
+    </span>
+
+    // good
+    <span data-toggle="tooltip">
+      Text
+    </span>
+  ```
+
+1. Tooltips: When using a tooltip, include the tooltip mixin
+
+1. Don't change `data-original-title`.
+  ```javascript
+    // bad
+    <span data-original-title="tooltip text">Foo</span>
+
+    // good
+    <span title="tooltip text">Foo</span>
+
+    $('span').tooltip('fixTitle');
+  ```
 
 
 ## SCSS
@@ -413,3 +495,5 @@ See [our current .eslintrc][eslintrc] for specific rules and patterns.
 
 [airbnb-js-style-guide]: https://github.com/airbnb/javascript
 [eslintrc]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.eslintrc
+[eslint-this]: http://eslint.org/docs/rules/class-methods-use-this
+[eslint-new]: http://eslint.org/docs/rules/no-new
diff --git a/doc/development/fe_guide/testing.md b/doc/development/fe_guide/testing.md
index 8d3513d3566..0ef9fc61a61 100644
--- a/doc/development/fe_guide/testing.md
+++ b/doc/development/fe_guide/testing.md
@@ -1,11 +1,20 @@
 # Frontend Testing
 
-There are two types of tests you'll encounter while developing frontend code
-at GitLab.  We use Karma and Jasmine for JavaScript unit testing, and RSpec
-feature tests with Capybara for integration testing.
+There are two types of test suites you'll encounter while developing frontend code
+at GitLab.  We use Karma and Jasmine for JavaScript unit and integration testing, and RSpec
+feature tests with Capybara for e2e (end-to-end) integration testing.
 
-Feature tests need to be written for all new features. Regression tests ought
-to be written for all bug fixes to prevent them from recurring in the future.
+Unit and feature tests need to be written for all new features.
+Most of the time, you should use rspec for your feature tests.
+There are cases where the behaviour you are testing is not worth the time spent running the full application,
+for example, if you are testing styling, animation or small actions that don't involve the backend,
+you should write an integration test using Jasmine.
+
+![Testing priority triangle](img/testing_triangle.png)
+
+_This diagram demonstrates the relative priority of each test type we use_
+
+Regression tests should be written for bug fixes to prevent them from recurring in the future.
 
 See [the Testing Standards and Style Guidelines](../testing.md)
 for more information on general testing practices at GitLab.
@@ -13,9 +22,126 @@ for more information on general testing practices at GitLab.
 ## Karma test suite
 
 GitLab uses the [Karma][karma] test runner with [Jasmine][jasmine] as its test
-framework for our JavaScript unit tests.  For tests that rely on DOM
-manipulation we use fixtures which are pre-compiled from HAML source files and
-served during testing by the [jasmine-jquery][jasmine-jquery] plugin.
+framework for our JavaScript unit and integration tests. For integration tests,
+we generate HTML files using RSpec (see `spec/javascripts/fixtures/*.rb` for examples).
+Some fixtures are still HAML templates that are translated to HTML files using the same mechanism (see `static_fixtures.rb`).
+Adding these static fixtures should be avoided as they are harder to keep up to date with real views.
+The existing static fixtures will be migrated over time.
+Please see [gitlab-org/gitlab-ce#24753](https://gitlab.com/gitlab-org/gitlab-ce/issues/24753) to track our progress.
+Fixtures are served during testing by the [jasmine-jquery][jasmine-jquery] plugin.
+
+JavaScript tests live in `spec/javascripts/`, matching the folder structure
+of `app/assets/javascripts/`: `app/assets/javascripts/behaviors/autosize.js`
+has a corresponding `spec/javascripts/behaviors/autosize_spec.js` file.
+
+Keep in mind that in a CI environment, these tests are run in a headless
+browser and you will not have access to certain APIs, such as
+[`Notification`](https://developer.mozilla.org/en-US/docs/Web/API/notification),
+which will have to be stubbed.
+
+### Best practice
+
+#### Naming unit tests
+
+When writing describe test blocks to test specific functions/methods,
+please use the method name as the describe block name.
+
+```javascript
+// Good
+describe('methodName', () => {
+  it('passes', () => {
+    expect(true).toEqual(true);
+  });
+});
+
+// Bad
+describe('#methodName', () => {
+  it('passes', () => {
+    expect(true).toEqual(true);
+  });
+});
+
+// Bad
+describe('.methodName', () => {
+  it('passes', () => {
+    expect(true).toEqual(true);
+  });
+});
+```
+#### Testing Promises
+
+When testing Promises you should always make sure that the test is asynchronous and rejections are handled.
+Your Promise chain should therefore end with a call of the `done` callback and `done.fail` in case an error occurred.
+
+```javascript
+// Good
+it('tests a promise', (done) => {
+  promise
+    .then((data) => {
+      expect(data).toBe(asExpected);
+    })
+    .then(done)
+    .catch(done.fail);
+});
+
+// Good
+it('tests a promise rejection', (done) => {
+  promise
+    .then(done.fail)
+    .catch((error) => {
+      expect(error).toBe(expectedError);
+    })
+    .then(done)
+    .catch(done.fail);
+});
+
+// Bad (missing done callback)
+it('tests a promise', () => {
+  promise
+    .then((data) => {
+      expect(data).toBe(asExpected);
+    })
+});
+
+// Bad (missing catch)
+it('tests a promise', (done) => {
+  promise
+    .then((data) => {
+      expect(data).toBe(asExpected);
+    })
+    .then(done)
+});
+
+// Bad (use done.fail in asynchronous tests)
+it('tests a promise', (done) => {
+  promise
+    .then((data) => {
+      expect(data).toBe(asExpected);
+    })
+    .then(done)
+    .catch(fail)
+});
+
+// Bad (missing catch)
+it('tests a promise rejection', (done) => {
+  promise
+    .catch((error) => {
+      expect(error).toBe(expectedError);
+    })
+    .then(done)
+});
+```
+
+#### Stubbing
+
+For unit tests, you should stub methods that are unrelated to the current unit you are testing.
+If you need to use a prototype method, instantiate an instance of the class and call it there instead of mocking the instance completely.
+
+For integration tests, you should stub methods that will effect the stability of the test if they
+execute their original behaviour. i.e. Network requests.
+
+### Vue.js unit tests
+See this [section][vue-test].
 
 ### Running frontend tests
 
@@ -80,24 +206,23 @@ If an integration test depends on JavaScript to run correctly, you need to make
 sure the spec is configured to enable JavaScript when the tests are run. If you
 don't do this you'll see vague error messages from the spec runner.
 
-To enable a JavaScript driver in an `rspec` test, add `js: true` to the
+To enable a JavaScript driver in an `rspec` test, add `:js` to the
 individual spec or the context block containing multiple specs that need
 JavaScript enabled:
 
 ```ruby
-
 # For one spec
-it 'presents information about abuse report', js: true do
-    # assertions...
+it 'presents information about abuse report', :js do
+  # assertions...
 end
 
-describe "Admin::AbuseReports", js: true do
-    it 'presents information about abuse report' do
-        # assertions...
-    end
-    it 'shows buttons for adding to abuse report' do
-        # assertions...
-    end
+describe "Admin::AbuseReports", :js do
+  it 'presents information about abuse report' do
+    # assertions...
+  end
+  it 'shows buttons for adding to abuse report' do
+    # assertions...
+  end
 end
 ```
 
@@ -113,13 +238,12 @@ file for the failing spec, add the `@javascript` flag above the Scenario:
 ```
 @javascript
 Scenario: Developer can approve merge request
-    Given I am a "Shop" developer
-    And I visit project "Shop" merge requests page
-    And merge request 'Bug NS-04' must be approved
-    And I click link "Bug NS-04"
-    When I click link "Approve"
-    Then I should see approved merge request "Bug NS-04"
-
+  Given I am a "Shop" developer
+  And I visit project "Shop" merge requests page
+  And merge request 'Bug NS-04' must be approved
+  And I click link "Bug NS-04"
+  When I click link "Approve"
+  Then I should see approved merge request "Bug NS-04"
 ```
 
 [capybara]: http://teamcapybara.github.io/capybara/
@@ -127,3 +251,4 @@ Scenario: Developer can approve merge request
 [jasmine-focus]: https://jasmine.github.io/2.5/focused_specs.html
 [jasmine-jquery]: https://github.com/velesin/jasmine-jquery
 [karma]: http://karma-runner.github.io/
+[vue-test]:https://docs.gitlab.com/ce/development/fe_guide/vue.html#testing-vue-components
diff --git a/doc/development/fe_guide/vue.md b/doc/development/fe_guide/vue.md
index 3e3406e7d6a..a984bb6c94c 100644
--- a/doc/development/fe_guide/vue.md
+++ b/doc/development/fe_guide/vue.md
@@ -19,13 +19,31 @@ We don't want to refactor all GitLab frontend code into Vue.js, here are some gu
 when not to use Vue.js:
 
 - Adding or changing static information;
-- Features that highly depend on jQuery will be hard to work with Vue.js
+- Features that highly depend on jQuery will be hard to work with Vue.js;
+- Features without reactive data;
 
 As always, the Frontend Architectural Experts are available to help with any Vue or JavaScript questions.
 
-## How to build a new feature with Vue.js
+## Vue architecture
 
-**Components, Stores and Services**
+All new features built with Vue.js must follow a [Flux architecture][flux].
+The main goal we are trying to achieve is to have only one data flow and only one data entry.
+In order to achieve this goal, each Vue bundle needs a Store - where we keep all the data -,
+a Service - that we use to communicate with the server - and a main Vue component.
+
+Think of the Main Vue Component as the entry point of your application. This is the only smart
+component that should exist in each Vue feature.
+This component is responsible for:
+1. Calling the Service to get data from the server
+1. Calling the Store to store the data received
+1. Mounting all the other components
+
+  ![Vue Architecture](img/vue_arch.png)
+
+You can also read about this architecture in vue docs about [state management][state-management]
+and about [one way data flow][one-way-data-flow].
+
+### Components, Stores and Services
 
 In some features implemented with Vue.js, like the [issue board][issue-boards]
 or [environments table][environments-table]
@@ -46,16 +64,17 @@ _For consistency purposes, we recommend you to follow the same structure._
 
 Let's look into each of them:
 
-**A `*_bundle.js` file**
+### A `*_bundle.js` file
 
 This is the index file of your new feature. This is where the root Vue instance
 of the new feature should be.
 
-The Store and the Service should be imported and initialized in this file and provided as a prop to the main component.
+The Store and the Service should be imported and initialized in this file and
+provided as a prop to the main component.
 
 Don't forget to follow [these steps.][page_specific_javascript]
 
-**A folder for Components**
+### A folder for Components
 
 This folder holds all components that are specific of this new feature.
 If you need to use or create a component that will probably be used somewhere
@@ -70,20 +89,219 @@ in one table would not be a good use of this pattern.
 
 You can read more about components in Vue.js site, [Component System][component-system]
 
-**A folder for the Store**
+### A folder for the Store
 
 The Store is a class that allows us to manage the state in a single
-source of truth.
+source of truth. It is not aware of the service or the components.
 
 The concept we are trying to follow is better explained by Vue documentation
 itself, please read this guide: [State Management][state-management]
 
-**A folder for the Service**
+### A folder for the Service
+
+The Service is a class used only to communicate with the server.
+It does not store or manipulate any data. It is not aware of the store or the components.
+We use [vue-resource][vue-resource-repo] to communicate with the server.
+
+Vue Resource should only be imported in the service file.
+
+  ```javascript
+  import Vue from 'vue';
+  import VueResource from 'vue-resource';
+
+  Vue.use(VueResource);
+  ```
+
+### CSRF token
+We use a Vue Resource interceptor to manage the CSRF token.
+`app/assets/javascripts/vue_shared/vue_resource_interceptor.js` holds all our common interceptors.
+Note: You don't need to load `app/assets/javascripts/vue_shared/vue_resource_interceptor.js`
+since it's already being loaded by `common_vue.js`.
+
+### End Result
+
+The following example shows an  application:
+
+```javascript
+// store.js
+export default class Store {
+
+  /**  
+   * This is where we will iniatialize the state of our data.
+   * Usually in a small SPA you don't need any options when starting the store. In the case you do
+   * need guarantee it's an Object and it's documented.
+   *    
+   * @param  {Object} options   
+   */   
+  constructor(options) {
+    this.options = options;
+
+    // Create a state object to handle all our data in the same place
+    this.todos = []:
+  }
+
+  setTodos(todos = []) {
+    this.todos = todos;
+  }
+
+  addTodo(todo) {
+    this.todos.push(todo);
+  }
+
+  removeTodo(todoID) {
+    const state = this.todos;
+
+    const newState = state.filter((element) => {element.id !== todoID});
+
+    this.todos = newState;
+  }
+}
+
+// service.js
+import Vue from 'vue';
+import VueResource from 'vue-resource';
+import 'vue_shared/vue_resource_interceptor';
+
+Vue.use(VueResource);
+
+export default class Service {
+  constructor(options) {
+    this.todos = Vue.resource(endpoint.todosEndpoint);
+  }
+
+  getTodos() {
+    return this.todos.get();
+  }
+
+  addTodo(todo) {
+    return this.todos.put(todo);
+  }
+}
+// todo_component.vue
+<script>
+export default {
+  props: {
+    data: {
+      type: Object,
+      required: true,
+    },
+  }
+}
+</script>
+<template>
+  <div>
+    <h1>
+      Title: {{data.title}}
+    </h1>
+    <p>
+      {{data.text}}
+    </p>
+  </div>
+</template>
+
+// todos_main_component.vue
+<script>
+import Store from 'store';
+import Service from 'service';
+import TodoComponent from 'todoComponent';
+export default {
+  /**  
+   * Although most data belongs in the store, each component it's own state.
+   * We want to show a loading spinner while we are fetching the todos, this state belong
+   * in the component.
+   *
+   * We need to access the store methods through all methods of our component.
+   * We need to access the state of our store.
+   */   
+  data() {
+    const store = new Store();
+
+    return {
+      isLoading: false,
+      store: store,
+      todos: store.todos,
+    };
+  },
+
+  components: {
+    todo: TodoComponent,
+  },
+
+  created() {
+    this.service = new Service('todos');
+
+    this.getTodos();
+  },
+
+  methods: {
+    getTodos() {
+      this.isLoading = true;
+
+      this.service.getTodos()
+        .then(response => response.json())
+        .then((response) => {
+          this.store.setTodos(response);
+          this.isLoading = false;
+        })
+        .catch(() => {
+          this.isLoading = false;
+          // Show an error
+        });
+    },
+
+    addTodo(todo) {
+      this.service.addTodo(todo)
+      then(response => response.json())
+      .then((response) => {
+        this.store.addTodo(response);
+      })
+      .catch(() => {
+        // Show an error
+      });
+    }
+  }
+}
+</script>
+<template>
+  <div class="container">
+    <div v-if="isLoading">
+      <i
+        class="fa fa-spin fa-spinner"
+        aria-hidden="true" />
+    </div>
+
+    <div
+      v-if="!isLoading"
+      class="js-todo-list">
+      <template v-for='todo in todos'>
+        <todo :data="todo" />
+      </template>
+
+      <button
+        @click="addTodo"
+        class="js-add-todo">
+        Add Todo
+      </button>
+    </div>
+  <div>
+</template>
+
+// bundle.js
+import todoComponent from 'todos_main_component.vue';
+
+new Vue({
+  el: '.js-todo-app',
+  components: {
+    todoComponent,
+  },
+  render: createElement => createElement('todo-component' {
+    props: {
+      someProp: [],
+    }
+  }),
+});
 
-The Service is used only to communicate with the server.
-It does not store or manipulate any data.
-We use [vue-resource][vue-resource-repo] to
-communicate with the server.
+```
 
 The [issue boards service][issue-boards-service]
 is a good example of this pattern.
@@ -93,6 +311,128 @@ is a good example of this pattern.
 Please refer to the Vue section of our [style guide](style_guide_js.md#vuejs)
 for best practices while writing your Vue components and templates.
 
+## Testing Vue Components
+
+Each Vue component has a unique output. This output is always present in the render function.
+
+Although we can test each method of a Vue component individually, our goal must be to test the output
+of the render/template function, which represents the state at all times.
+
+Make use of Vue Resource Interceptors to mock data returned by the service.
+
+Here's how we would test the Todo App above:
+
+```javascript
+import component from 'todos_main_component';
+
+describe('Todos App', () => {
+  it('should render the loading state while the request is being made', () => {
+    const Component = Vue.extend(component);
+
+    const vm = new Component().$mount();
+
+    expect(vm.$el.querySelector('i.fa-spin')).toBeDefined();
+  });
+
+  describe('with data', () => {
+    // Mock the service to return data
+    const interceptor = (request, next) => {
+      next(request.respondWith(JSON.stringify([{
+        title: 'This is a todo',
+        body: 'This is the text'
+      }]), {
+        status: 200,
+      }));
+    };
+
+    let vm;
+
+    beforeEach(() => {
+      Vue.http.interceptors.push(interceptor);
+
+      const Component = Vue.extend(component);
+
+      vm = new Component().$mount();
+    });
+
+    afterEach(() => {
+      Vue.http.interceptors = _.without(Vue.http.interceptors, interceptor);
+    });
+
+
+    it('should render todos', (done) => {
+      setTimeout(() => {
+        expect(vm.$el.querySelectorAll('.js-todo-list div').length).toBe(1);
+        done();
+      }, 0);
+    });
+  });
+
+  describe('add todo', () => {
+    let vm;
+    beforeEach(() => {
+      const Component = Vue.extend(component);
+      vm = new Component().$mount();
+    });
+    it('should add a todos', (done) => {
+      setTimeout(() => {
+        vm.$el.querySelector('.js-add-todo').click();
+
+        // Add a new interceptor to mock the add Todo request
+        Vue.nextTick(() => {
+          expect(vm.$el.querySelectorAll('.js-todo-list div').length).toBe(2);
+        });
+      }, 0);
+    });
+  });
+});
+```
+#### Test the component's output
+The main return value of a Vue component is the rendered output. In order to test the component we
+need to test the rendered output. [Vue][vue-test] guide's to unit test show us exactly that:
+
+
+### Stubbing API responses
+[Vue Resource Interceptors][vue-resource-interceptor] allow us to add a interceptor with
+the response we need:
+
+```javascript
+  // Mock the service to return data
+  const interceptor = (request, next) => {
+    next(request.respondWith(JSON.stringify([{
+      title: 'This is a todo',
+      body: 'This is the text'
+    }]), {
+      status: 200,
+    }));
+  };
+
+  beforeEach(() => {
+    Vue.http.interceptors.push(interceptor);
+  });
+
+  afterEach(() => {
+    Vue.http.interceptors = _.without(Vue.http.interceptors, interceptor);
+  });
+
+  it('should do something', (done) => {
+    setTimeout(() => {
+      // Test received data
+      done();
+    }, 0);
+  });
+```
+
+1. Use `$.mount()` to mount the component
+```javascript
+  // bad
+  new Component({
+    el: document.createElement('div')
+  });
+
+  // good
+  new Component().$mount();
+```
 
 [vue-docs]: http://vuejs.org/guide/index.html
 [issue-boards]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/app/assets/javascripts/boards
@@ -100,5 +440,9 @@ for best practices while writing your Vue components and templates.
 [page_specific_javascript]: https://docs.gitlab.com/ce/development/frontend.html#page-specific-javascript
 [component-system]: https://vuejs.org/v2/guide/#Composing-with-Components
 [state-management]: https://vuejs.org/v2/guide/state-management.html#Simple-State-Management-from-Scratch
+[one-way-data-flow]: https://vuejs.org/v2/guide/components.html#One-Way-Data-Flow
 [vue-resource-repo]: https://github.com/pagekit/vue-resource
+[vue-resource-interceptor]: https://github.com/pagekit/vue-resource/blob/develop/docs/http.md#interceptors
+[vue-test]: https://vuejs.org/v2/guide/unit-testing.html
 [issue-boards-service]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/assets/javascripts/boards/services/board_service.js.es6
+[flux]: https://facebook.github.io/flux