1 files changed, 47 insertions, 3 deletions
diff --git a/doc/development/fe_guide/vue.md b/doc/development/fe_guide/vue.md
index 396467b47d1..bca24e6ee0b 100644
--- a/doc/development/fe_guide/vue.md
+++ b/doc/development/fe_guide/vue.md
@@ -1,6 +1,6 @@
 # Vue
 
-To get started with Vue, read through [their documentation][vue-docs].
+To get started with Vue, read through [their documentation](https://vuejs.org/v2/guide/).
 
 ## Examples
 
@@ -104,6 +104,51 @@ document.addEventListener('DOMContentLoaded', () => new Vue({
 }));
 ```
 
+#### Accessing feature flags
+
+Use Vue's [provide/inject](https://vuejs.org/v2/api/#provide-inject) mechanism
+to make feature flags available to any descendant components in a Vue
+application. The `glFeatures` object is already provided in `commons/vue.js`, so
+only the mixin is required to utilize the flags:
+
+```javascript
+// An arbitrary descendant component
+
+import glFeatureFlagsMixin from '~/vue_shared/mixins/gl_feature_flags_mixin';
+
+export default {
+  // ...
+  mixins: [glFeatureFlagsMixin()],
+  // ...
+  created() {
+    if (this.glFeatures.myFlag) {
+      // ...
+    }
+  },
+}
+```
+
+This approach has a few benefits:
+
+- Arbitrarily deeply nested components can opt-in and access the flag without
+  intermediate components being aware of it (c.f. passing the flag down via
+  props).
+- Good testability, since the flag can be provided to `mount`/`shallowMount`
+  from `vue-test-utils` as easily as a prop.
+
+  ```javascript
+  import { shallowMount } from '@vue/test-utils';
+
+  shallowMount(component, {
+    provide: {
+      glFeatures: { myFlag: true },
+    },
+  });
+  ```
+
+- No need to access a global variable, except in the application's
+  [entry point](#accessing-the-gl-object).
+
 ### A folder for Components
 
 This folder holds all components that are specific of this new feature.
@@ -245,7 +290,6 @@ One should apply to be a Vue.js expert by opening an MR when the Merge Request's
 - Vuex code follows the [documented pattern](vuex.md#actions-pattern-request-and-receive-namespaces)
 - Knowledge about the existing Vue and Vuex applications and existing reusable components
 
-[vue-docs]: http://vuejs.org/guide/index.html
 [issue-boards]: https://gitlab.com/gitlab-org/gitlab-foss/tree/master/app/assets/javascripts/boards
 [environments-table]: https://gitlab.com/gitlab-org/gitlab-foss/tree/master/app/assets/javascripts/environments
 [page_specific_javascript]: ./performance.md#page-specific-javascript
@@ -253,5 +297,5 @@ One should apply to be a Vue.js expert by opening an MR when the Merge Request's
 [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-test]: https://vuejs.org/v2/guide/unit-testing.html
-[flux]: https://facebook.github.io/flux
+[flux]: https://facebook.github.io/flux/
 [axios]: https://github.com/axios/axios