Merge remote-tracking branch 'upstream/master' into 14995-custom_wiki_sidebar

* upstream/master: (4180 commits)
  Enable frozen string literals for app/workers/*.rb
  Resolve "Search dropdown hides & shows when typing"
  Revert merge request widget button max height
  Update CHANGELOG.md for 11.0.2
  Update external link icon in header user dropdown
  Added Diff Viewer to new VUE based MR page
  Fixed eslint failure in IDE spec helpers
  Use refs instead of querySelector.
  Show file in tree on WebIDE open
  Resolve "Remove unused bootstrap component CSS"
  Resolve "Explain what Groups are in the New Group page"
  [QA] Make sure we wait for the deploy key list to load
  Update _scopes_form.html.haml to remove duplicate information
  Use the branch instead of the tag to install
  port the EE changes
  Add index on deployable_type/id for deployments
  Add a helper to rename a column using a background migration
  Fix performance bottleneck when rendering large wiki pages
  Port Namespace#root_ancestor to CE
  Remove duplicate spec
  ...

51 files changed, 3266 insertions, 1521 deletions

diff --git a/doc/development/README.md b/doc/development/README.md
index 45e9565f9a7..5d6fed5bc72 100644
--- a/doc/development/README.md
+++ b/doc/development/README.md
@@ -1,5 +1,6 @@
 ---
 comments: false
+description: 'Learn how to contribute to GitLab.'
 ---
 
 # GitLab development guides
@@ -18,6 +19,7 @@ comments: false
 - [Code review guidelines](code_review.md) for reviewing code and having code reviewed.
 - [Automatic CE->EE merge](automatic_ce_ee_merge.md)
 - [Guidelines for implementing Enterprise Edition features](ee_features.md)
+- [Security process for developers](https://gitlab.com/gitlab-org/release/docs/blob/master/general/security/developer.md#security-releases-critical-non-critical-as-a-developer)
 
 ## UX and frontend guides
 
@@ -30,6 +32,8 @@ comments: false
 - [GitLab utilities](utilities.md)
 - [API styleguide](api_styleguide.md) Use this styleguide if you are
   contributing to the API.
+- [GraphQL API styleguide](api_graphql_styleguide.md) Use this
+  styleguide if you are contribution to the [GraphQL API](../api/graphql/index.md)
 - [Sidekiq guidelines](sidekiq_style_guide.md) for working with Sidekiq workers
 - [Working with Gitaly](gitaly.md)
 - [Manage feature flags](feature_flags.md)
@@ -39,9 +43,9 @@ comments: false
 - [Sidekiq debugging](sidekiq_debugging.md)
 - [Gotchas](gotchas.md) to avoid
 - [Avoid modules with instance variables](module_with_instance_variables.md) if possible
-- [Issue and merge requests state models](object_state_models.md)
 - [How to dump production data to staging](db_dump.md)
 - [Working with the GitHub importer](github_importer.md)
+- [Working with Merge Request diffs](diffs.md)
 
 ## Performance guides
 
@@ -84,8 +88,8 @@ comments: false
 
 ## Documentation guides
 
-- [Writing documentation](writing_documentation.md)
-- [Documentation styleguide](doc_styleguide.md)
+- [Writing documentation](documentation/index.md)
+- [Documentation styleguide](documentation/styleguide.md)
 - [Markdown](../user/markdown.md)
 
 ## Internationalization (i18n) guides
diff --git a/doc/development/api_graphql_styleguide.md b/doc/development/api_graphql_styleguide.md
new file mode 100644
index 00000000000..f74e4f0bd7e
--- /dev/null
+++ b/doc/development/api_graphql_styleguide.md
@@ -0,0 +1,81 @@
+# GraphQL API
+
+## Authentication
+
+Authentication happens through the `GraphqlController`, right now this
+uses the same authentication as the Rails application. So the session
+can be shared.
+
+It is also possible to add a `private_token` to the querystring, or
+add a `HTTP_PRIVATE_TOKEN` header.
+
+### Authorization
+
+Fields can be authorized using the same abilities used in the Rails
+app. This can be done using the `authorize` helper:
+
+```ruby
+module Types
+  class QueryType < BaseObject
+    graphql_name 'Query'
+
+    field :project, Types::ProjectType, null: true, resolver: Resolvers::ProjectResolver do
+      authorize :read_project
+    end
+  end
+```
+
+The object found by the resolve call is used for authorization.
+
+This works for authorizing a single record, for authorizing
+collections, we should only load what the currently authenticated user
+is allowed to view. Preferably we use our existing finders for that.
+
+## Types
+
+When exposing a model through the GraphQL API, we do so by creating a
+new type in `app/graphql/types`.
+
+When exposing properties in a type, make sure to keep the logic inside
+the definition as minimal as possible. Instead, consider moving any
+logic into a presenter:
+
+```ruby
+class Types::MergeRequestType < BaseObject
+  present_using MergeRequestPresenter
+
+  name 'MergeRequest'
+end
+```
+
+An existing presenter could be used, but it is also possible to create
+a new presenter specifically for GraphQL.
+
+The presenter is initialized using the object resolved by a field, and
+the context.
+
+## Resolvers
+
+To find objects to display in a field, we can add resolvers to
+`app/graphql/resolvers`.
+
+Arguments can be defined within the resolver, those arguments will be
+made available to the fields using the resolver.
+
+We already have a `FullPathLoader` that can be included in other
+resolvers to quickly find Projects and Namespaces which will have a
+lot of dependant objects.
+
+To limit the amount of queries performed, we can use `BatchLoader`.
+
+## Testing
+
+_full stack_ tests for a graphql query or mutation live in
+`spec/requests/api/graphql`.
+
+When adding a query, the `a working graphql query` shared example can
+be used to test if the query renders valid results.
+
+Using the `GraphqlHelpers#all_graphql_fields_for`-helper, a query
+including all available fields can be constructed. This makes it easy
+to add a test rendering all possible fields for a query.
diff --git a/doc/development/background_migrations.md b/doc/development/background_migrations.md
index fc1b202b5eb..46c5baddb9c 100644
--- a/doc/development/background_migrations.md
+++ b/doc/development/background_migrations.md
@@ -24,7 +24,7 @@ Some examples where background migrations can be useful:
 
 * Migrating events from one table to multiple separate tables.
 * Populating one column based on JSON stored in another column.
-* Migrating data that depends on the output of exernal services (e.g. an API).
+* Migrating data that depends on the output of external services (e.g. an API).
 
 ## Isolation
 
@@ -46,7 +46,7 @@ See [Sidekiq best practices guidelines](https://github.com/mperham/sidekiq/wiki/
 for more details.
 
 Make sure that in case that your migration job is going to be retried data
-integrity is guarateed.
+integrity is guaranteed.
 
 ## How It Works
 
@@ -133,11 +133,19 @@ roughly be as follows:
 1. Release B:
   1. Deploy code so that the application starts using the new column and stops
      scheduling jobs for newly created data.
-  1. In a post-deployment migration you'll need to ensure no jobs remain. To do
-     so you can use `Gitlab::BackgroundMigration.steal` to process any remaining
-     jobs before continuing.
+  1. In a post-deployment migration you'll need to ensure no jobs remain.
+     1. Use `Gitlab::BackgroundMigration.steal` to process any remaining
+        jobs in Sidekiq.
+     1. Reschedule the migration to be run directly (i.e. not through Sidekiq)
+        on any rows that weren't migrated by Sidekiq. This can happen if, for
+        instance, Sidekiq received a SIGKILL, or if a particular batch failed
+        enough times to be marked as dead.
   1. Remove the old column.
 
+This may also require a bump to the [import/export version][import-export], if
+importing a project from a prior version of GitLab requires the data to be in
+the new format.
+
 ## Example
 
 To explain all this, let's use the following example: the table `services` has a
@@ -296,3 +304,4 @@ for more details.
 [migrations-readme]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/spec/migrations/README.md
 [issue-rspec-hooks]: https://gitlab.com/gitlab-org/gitlab-ce/issues/35351
 [reliable-sidekiq]: https://gitlab.com/gitlab-org/gitlab-ce/issues/36791
+[import-export]: ../user/project/settings/import_export.md
diff --git a/doc/development/changelog.md b/doc/development/changelog.md
index 1962392a9eb..9e0c81b3d60 100644
--- a/doc/development/changelog.md
+++ b/doc/development/changelog.md
@@ -22,7 +22,7 @@ The `merge_request` value is a reference to a merge request that adds this
 entry, and the `author` key is used to give attribution to community
 contributors. **Both are optional**.
 The `type` field maps the category of the change,
-valid options are: added, fixed, changed, deprecated, removed, security, other. **Type field is mandatory**.
+valid options are: added, fixed, changed, deprecated, removed, security, performance, other. **Type field is mandatory**.
 
 Community contributors and core team members are encouraged to add their name to
 the `author` field. GitLab team members **should not**.
@@ -44,6 +44,9 @@ the `author` field. GitLab team members **should not**.
 - _Any_ contribution from a community member, no matter how small, **may** have
   a changelog entry regardless of these guidelines if the contributor wants one.
   Example: "Fixed a typo on the search results page. (Jane Smith)"
+- Performance improvements **should** have a changelog entry.
+- Any change that introduces a database migration **must** have a
+  changelog entry.
 
 ## Writing good changelog entries
 
diff --git a/doc/development/code_review.md b/doc/development/code_review.md
index 7165b8062a7..23c80799235 100644
--- a/doc/development/code_review.md
+++ b/doc/development/code_review.md
@@ -22,13 +22,17 @@ There are a few rules to get your merge request accepted:
   1. If your merge request includes UX, frontend and backend changes [^1], it must
     be **approved by a [UX team member, a frontend and a backend maintainer][team]**.
   1. If your merge request includes a new dependency or a filesystem change, it must
-    be **approved by a [Build team member][team]**. See [how to work with the Build team][build handbook] for more details.
+    be *approved by a [Distribution team member][team]*. See how to work with the [Distribution team for more details.](https://about.gitlab.com/handbook/engineering/dev-backend/distribution/)
 1. To lower the amount of merge requests maintainers need to review, you can
   ask or assign any [reviewers][projects] for a first review.
   1. If you need some guidance (e.g. it's your first merge request), feel free
     to ask one of the [Merge request coaches][team].
   1. The reviewer will assign the merge request to a maintainer once the
     reviewer is satisfied with the state of the merge request.
+1. Keep in mind that maintainers are also going to perform a final code review.
+   The ideal scenario is that the reviewer has already addressed any concerns
+   the maintainer would have found, and the maintainer only has to perform the
+   merge, but be prepared for further review comments.
 
 For more guidance, see [CONTRIBUTING.md](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/CONTRIBUTING.md).
 
@@ -207,3 +211,4 @@ Largely based on the [thoughtbot code review guide].
 [projects]: https://about.gitlab.com/handbook/engineering/projects/
 [team]: https://about.gitlab.com/team/
 [build handbook]: https://about.gitlab.com/handbook/build/handbook/build#how-to-work-with-build
+[^1]: Please note that specs other than JavaScript specs are considered backend code.
diff --git a/doc/development/database_debugging.md b/doc/development/database_debugging.md
index 32f392f1303..9c31265e417 100644
--- a/doc/development/database_debugging.md
+++ b/doc/development/database_debugging.md
@@ -11,7 +11,7 @@ Available `RAILS_ENV`
 
  - `production` (generally not for your main GDK db, but you may need this for e.g. omnibus)
  - `development` (this is your main GDK db)
- - `test` (used for tests like rspec and spinach)
+ - `test` (used for tests like rspec)
 
 
 ## Nuke everything and start over
diff --git a/doc/development/diffs.md b/doc/development/diffs.md
new file mode 100644
index 00000000000..55fc16e0b33
--- /dev/null
+++ b/doc/development/diffs.md
@@ -0,0 +1,115 @@
+# Working with Merge Request diffs
+
+Currently we rely on different sources to present merge request diffs, these include:
+
+- Rugged gem
+- Gitaly service
+- Database (through `merge_request_diff_files`)
+- Redis (cached highlighted diffs)
+
+We're constantly moving Rugged calls to Gitaly and the progress can be followed through [Gitaly repo](https://gitlab.com/gitlab-org/gitaly).
+
+## Architecture overview
+
+When refreshing a Merge Request (pushing to a source branch, force-pushing to target branch, or if the target branch now contains any commits from the MR)
+we fetch the comparison information using `Gitlab::Git::Compare`, which fetches `base` and `head` data using Gitaly and diff between them through
+`Gitlab::Git::Diff.between` (which uses _Gitaly_ if it's enabled, otherwise _Rugged_).
+The diffs fetching process _limits_ single file diff sizes and the overall size of the whole diff through a series of constant values. Raw diff files are
+then persisted on `merge_request_diff_files` table. 
+
+Even though diffs higher than 10kb are collapsed (`Gitlab::Git::Diff::COLLAPSE_LIMIT`), we still keep them on Postgres. However, diff files over _safety limits_
+(see the [Diff limits section](#diff-limits)) are _not_ persisted.
+
+In order to present diffs information on the Merge Request diffs page, we:
+
+1. Fetch all diff files from database `merge_request_diff_files`
+2. Fetch the _old_ and _new_ file blobs in batch to:
+  1. Highlight old and new file content
+  2. Know which viewer it should use for each file (text, image, deleted, etc)
+  3. Know if the file content changed
+  4. Know if it was stored externally
+  5. Know if it had storage errors
+3. If the diff file is cacheable (text-based), it's cached on Redis
+using `Gitlab::Diff::FileCollection::MergeRequestDiff`
+
+## Diff limits
+
+As explained above, we limit single diff files and the size of the whole diff. There are scenarios where we collapse the diff file,
+and cases where the diff file is not presented at all, and the user is guided to the Blob view. Here we'll go into details about
+these limits.
+
+### Diff collection limits
+
+Limits that act onto all diff files collection. Files number, lines number and files size are considered.
+
+```ruby
+Gitlab::Git::DiffCollection.collection_limits[:safe_max_files] = Gitlab::Git::DiffCollection::DEFAULT_LIMITS[:max_files] = 100
+```
+
+File diffs will be collapsed (but be expandable) if 100 files have already been rendered.
+
+
+```ruby
+Gitlab::Git::DiffCollection.collection_limits[:safe_max_lines] = Gitlab::Git::DiffCollection::DEFAULT_LIMITS[:max_lines] = 5000 
+```
+
+File diffs will be collapsed (but be expandable) if 5000 lines have already been rendered.
+
+
+```ruby
+Gitlab::Git::DiffCollection.collection_limits[:safe_max_bytes] = Gitlab::Git::DiffCollection.collection_limits[:safe_max_files] * 5.kilobytes = 500.kilobytes 
+```
+
+File diffs will be collapsed (but be expandable) if 500 kilobytes have already been rendered.
+
+
+```ruby
+Gitlab::Git::DiffCollection.collection_limits[:max_files] = Commit::DIFF_HARD_LIMIT_FILES = 1000 
+```
+
+No more files will be rendered at all if 1000 files have already been rendered.
+
+
+```ruby
+Gitlab::Git::DiffCollection.collection_limits[:max_lines] = Commit::DIFF_HARD_LIMIT_LINES = 50000 
+```
+
+No more files will be rendered at all if 50,000 lines have already been rendered.
+
+```ruby
+Gitlab::Git::DiffCollection.collection_limits[:max_bytes] = Gitlab::Git::DiffCollection.collection_limits[:max_files] * 5.kilobytes = 5000.kilobytes 
+```
+
+No more files will be rendered at all if 5 megabytes have already been rendered.
+
+
+### Individual diff file limits
+
+Limits that act onto each diff file of a collection. Files number, lines number and files size are considered.
+
+```ruby
+Gitlab::Git::Diff::COLLAPSE_LIMIT = 10.kilobytes
+```
+
+File diff will be collapsed (but be expandable) if it is larger than 10 kilobytes.
+
+```ruby
+Gitlab::Git::Diff::SIZE_LIMIT = 100.kilobytes
+```
+
+File diff will not be rendered if it's larger than 100 kilobytes.
+
+
+```ruby
+Commit::DIFF_SAFE_LINES = Gitlab::Git::DiffCollection::DEFAULT_LIMITS[:max_lines] = 5000
+```
+
+File diff will be suppressed (technically different from collapsed, but behaves the same, and is expandable) if it has more than 5000 lines.
+
+## Viewers
+
+Diff Viewers, which can be found on `models/diff_viewer/*` are classes used to map metadata about each type of Diff File. It has information
+whether it's a binary, which partial should be used to render it or which File extensions this class accounts for. 
+
+`DiffViewer::Base` validates _blobs_ (old and new versions) content, extension and file type in order to check if it can be rendered.
+
diff --git a/doc/development/doc_styleguide.md b/doc/development/doc_styleguide.md
index 41e3412c7ff..7d84f8ca86a 100644
--- a/doc/development/doc_styleguide.md
+++ b/doc/development/doc_styleguide.md
@@ -1,394 +1,3 @@
-# Documentation style guidelines
-
-The documentation style guide defines the markup structure used in
-GitLab documentation. Check the
-[documentation guidelines](writing_documentation.md) for general development instructions.
-
-Check the GitLab hanbook for the [writing styles guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines).
-
-## Text
-
-- Split up long lines (wrap text), this makes it much easier to review and edit. Only
-  double line breaks are shown as a full line break in [GitLab markdown][gfm].
-  80-100 characters is a good line length
-- Make sure that the documentation is added in the correct
-  [directory](writing_documentation.md#documentation-directory-structure) and that
-  there's a link to it somewhere useful
-- Do not duplicate information
-- Be brief and clear
-- Unless there's a logical reason not to, add documents in alphabetical order
-- Write in US English
-- Use [single spaces][] instead of double spaces
-- Jump a line between different markups (e.g., after every paragraph, hearder, list, etc)
-- Capitalize "G" and "L" in GitLab
-- Capitalize feature, products, and methods names. E.g.: GitLab Runner, Geo,
-Issue Boards, Git, Prometheus, Continuous Integration.
-
-## Formatting
-
-- Use dashes (`-`) for unordered lists instead of asterisks (`*`)
-- Use the number one (`1`) for ordered lists
-- Use underscores (`_`) to mark a word or text in italics
-- Use double asterisks (`**`) to mark a word or text in bold
-- When using lists, prefer not to end each item with a period. You can use
-  them if there are multiple sentences, just keep the last sentence without
-  a period
-
-## Headings
-
-- Add only one H1 title in each document, by adding `#` at the beginning of
-  it (when using markdown). For subheadings, use `##`, `###` and so on
-- Avoid putting numbers in headings. Numbers shift, hence documentation anchor
-  links shift too, which eventually leads to dead links. If you think it is
-  compelling to add numbers in headings, make sure to at least discuss it with
-  someone in the Merge Request
-- [Avoid using symbols and special chars](https://gitlab.com/gitlab-com/gitlab-docs/issues/84)
-  in headers. Whenever possible, they should be plain and short text.
-- Avoid adding things that show ephemeral statuses. For example, if a feature is
-  considered beta or experimental, put this info in a note, not in the heading.
-- When introducing a new document, be careful for the headings to be
-  grammatically and syntactically correct. Mention one or all
-  of the following GitLab members for a review: `@axil` or `@marcia`.
-  This is to ensure that no document with wrong heading is going
-  live without an audit, thus preventing dead links and redirection issues when
-  corrected
-- Leave exactly one newline after a heading
-
-## Links
-
-- Use the regular inline link markdown markup `[Text](https://example.com)`.
-  It's easier to read, review, and maintain.
-- If there's a link that repeats several times through the same document,
-  you can use `[Text][identifier]` and at the bottom of the section or the
-  document add: `[identifier]: https://example.com`, in which case, we do
-  encourage you to also add an alternative text: `[identifier]: https://example.com "Alternative text"` that appears when hovering your mouse on a link.
-- To link to internal documentation, use relative links, not full URLs. Use `../` to
-  navigate tp high-level directories, and always add the file name `file.md` at the
-  end of the link with the `.md` extension, not `.html`.
-  Example: instead of `[text](../../merge_requests/)`, use
-  `[text](../../merge_requests/index.md)` or, `[text](../../ci/README.md)`, or,
-  for anchor links, `[text](../../ci/README.md#examples)`.
-  Using the markdown extension is necessary for the [`/help`](writing_documentation.md#gitlab-help)
-  section of GitLab.
-- To link from CE to EE-only documentation, use the EE-only doc full URL.
-- Use [meaningful anchor texts](https://www.futurehosting.com/blog/links-should-have-meaningful-anchor-text-heres-why/).
-  E.g., instead of writing something like `Read more about GitLab Issue Boards [here](LINK)`,
-  write `Read more about [GitLab Issue Boards](LINK)`.
-
-## Images
-
-- Place images in a separate directory named `img/` in the same directory where
-  the `.md` document that you're working on is located. Always prepend their
-  names with the name of the document that they will be included in. For
-  example, if there is a document called `twitter.md`, then a valid image name
-  could be `twitter_login_screen.png`. [**Exception**: images for
-  [articles](writing_documentation.md#technical-articles) should be
-  put in a directory called `img` underneath `/articles/article_title/img/`, therefore,
-  there's no need to prepend the document name to their filenames.]
-- Images should have a specific, non-generic name that will differentiate them.
-- Keep all file names in lower case.
-- Consider using PNG images instead of JPEG.
-- Compress all images with <https://tinypng.com/> or similar tool.
-- Compress gifs with <https://ezgif.com/optimize> or similar tool.
-- Images should be used (only when necessary) to _illustrate_ the description
-of a process, not to _replace_ it.
-
-Inside the document:
-
-- The Markdown way of using an image inside a document is:
-  `![Proper description what the image is about](img/document_image_title.png)`
-- Always use a proper description for what the image is about. That way, when a
-  browser fails to show the image, this text will be used as an alternative
-  description
-- If there are consecutive images with little text between them, always add
-  three dashes (`---`) between the image and the text to create a horizontal
-  line for better clarity
-- If a heading is placed right after an image, always add three dashes (`---`)
-  between the image and the heading
-
-## Notes
-
-- Notes should be quoted with the word `Note:` being bold. Use this form:
-
-    ```md
-    >**Note:**
-    This is something to note.
-    ```
-
-    which renders to:
-
-    >**Note:**
-    This is something to note.
-
-    If the note spans across multiple lines it's OK to split the line.
-
-## Specific sections and terms
-
-To mention and/or reference specific terms in GitLab, please follow the styles
-below.
-
-### GitLab versions and tiers
-
-- Every piece of documentation that comes with a new feature should declare the
-  GitLab version that feature got introduced. Right below the heading add a
-  note:
-
-    ```md
-    > Introduced in GitLab 8.3.
-    ```
-
-- If possible every feature should have a link to the MR, issue, or epic that introduced it.
-  The above note would be then transformed to:
-
-    ```md
-    > [Introduced][ce-1242] in GitLab 8.3.
-    ```
-
-    , where the [link identifier](#links) is named after the repository (CE) and
-    the MR number.
-
-- If the feature is only available in GitLab Enterprise Edition, don't forget to mention
-  the [paid tier](https://about.gitlab.com/handbook/marketing/product-marketing/#tiers)
-  the feature is available in:
-
-    ```md
-    > [Introduced][ee-1234] in [GitLab Starter](https://about.gitlab.com/products/) 8.3.
-    ```
-
-    Otherwise, leave this mention out.
-
-### GitLab Restart
-
-There are many cases that a restart/reconfigure of GitLab is required. To
-avoid duplication, link to the special document that can be found in
-[`doc/administration/restart_gitlab.md`][doc-restart]. Usually the text will
-read like:
-
-  ```
-  Save the file and [reconfigure GitLab](../administration/restart_gitlab.md)
-  for the changes to take effect.
-  ```
-
-If the document you are editing resides in a place other than the GitLab CE/EE
-`doc/` directory, instead of the relative link, use the full path:
-`http://docs.gitlab.com/ce/administration/restart_gitlab.html`.
-Replace `reconfigure` with `restart` where appropriate.
-
-### Installation guide
-
-**Ruby:**
-In [step 2 of the installation guide](../install/installation.md#2-ruby),
-we install Ruby from source. Whenever there is a new version that needs to
-be updated, remember to change it throughout the codeblock and also replace
-the sha256sum (it can be found in the [downloads page][ruby-dl] of the Ruby
-website).
-
-[ruby-dl]: https://www.ruby-lang.org/en/downloads/ "Ruby download website"
-
-### Configuration documentation for source and Omnibus installations
-
-GitLab currently officially supports two installation methods: installations
-from source and Omnibus packages installations.
-
-Whenever there is a setting that is configurable for both installation methods,
-prefer to document it in the CE docs to avoid duplication.
-
-Configuration settings include:
-
-- settings that touch configuration files in `config/`
-- NGINX settings and settings in `lib/support/` in general
-
-When there is a list of steps to perform, usually that entails editing the
-configuration file and reconfiguring/restarting GitLab. In such case, follow
-the style below as a guide:
-
-```md
-**For Omnibus installations**
-
-1. Edit `/etc/gitlab/gitlab.rb`:
-
-    ```ruby
-    external_url "https://gitlab.example.com"
-    ```
-
-1. Save the file and [reconfigure] GitLab for the changes to take effect.
-
 ---
-
-**For installations from source**
-
-1. Edit `config/gitlab.yml`:
-
-    ```yaml
-    gitlab:
-      host: "gitlab.example.com"
-    ```
-
-1. Save the file and [restart] GitLab for the changes to take effect.
-
-
-[reconfigure]: path/to/administration/restart_gitlab.md#omnibus-gitlab-reconfigure
-[restart]: path/to/administration/restart_gitlab.md#installations-from-source
-```
-
-In this case:
-
-- before each step list the installation method is declared in bold
-- three dashes (`---`) are used to create a horizontal line and separate the
-  two methods
-- the code blocks are indented one or more spaces under the list item to render
-  correctly
-- different highlighting languages are used for each config in the code block
-- the [references](#references) guide is used for reconfigure/restart
-
-### Fake tokens
-
-There may be times where a token is needed to demonstrate an API call using
-cURL or a secret variable used in CI. It is strongly advised not to use real
-tokens in documentation even if the probability of a token being exploited is
-low.
-
-You can use the following fake tokens as examples.
-
-|     **Token type**    |           **Token value**         |
-| --------------------- | --------------------------------- |
-| Private user token    | `9koXpg98eAheJpvBs5tK`            |
-| Personal access token | `n671WNGecHugsdEDPsyo`            |
-| Application ID        | `2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6` |
-| Application secret    | `04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df` |
-| Secret CI variable    | `Li8j-mLUVA3eZYjPfd_H`            |
-| Specific Runner token | `yrnZW46BrtBFqM7xDzE7dddd`        |
-| Shared Runner token   | `6Vk7ZsosqQyfreAxXTZr`            |
-| Trigger token         | `be20d8dcc028677c931e04f3871a9b`  |
-| Webhook secret token  | `6XhDroRcYPM5by_h-HLY`            |
-| Health check token    | `Tu7BgjR9qeZTEyRzGG2P`            |
-| Request profile token | `7VgpS4Ax5utVD2esNstz`            |
-
-### API
-
-Here is a list of must-have items. Use them in the exact order that appears
-on this document. Further explanation is given below.
-
-- Every method must have the REST API request. For example:
-
-    ```
-    GET /projects/:id/repository/branches
-    ```
-
-- Every method must have a detailed
-  [description of the parameters](#method-description).
-- Every method must have a cURL example.
-- Every method must have a response body (in JSON format).
-
-#### Method description
-
-Use the following table headers to describe the methods. Attributes should
-always be in code blocks using backticks (``` ` ```).
-
-```
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-```
-
-Rendered example:
-
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `user`  | string | yes | The GitLab username |
-
-#### cURL commands
-
-- Use `https://gitlab.example.com/api/v4/` as an endpoint.
-- Wherever needed use this personal access token: `9koXpg98eAheJpvBs5tK`.
-- Always put the request first. `GET` is the default so you don't have to
-  include it.
-- Use double quotes to the URL when it includes additional parameters.
-- Prefer to use examples using the personal access token and don't pass data of
-  username and password.
-
-| Methods | Description |
-| ------- | ----------- |
-| `-H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK"` | Use this method as is, whenever authentication needed |
-| `-X POST`   | Use this method when creating new objects |
-| `-X PUT`    | Use this method when updating existing objects |
-| `-X DELETE` | Use this method when removing existing objects |
-
-#### cURL Examples
-
-Below is a set of [cURL][] examples that you can use in the API documentation.
-
-##### Simple cURL command
-
-Get the details of a group:
-
-```bash
-curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/gitlab-org
-```
-
-##### cURL example with parameters passed in the URL
-
-Create a new project under the authenticated user's namespace:
-
-```bash
-curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects?name=foo"
-```
-
-##### Post data using cURL's --data
-
-Instead of using `-X POST` and appending the parameters to the URI, you can use
-cURL's `--data` option. The example below will create a new project `foo` under
-the authenticated user's namespace.
-
-```bash
-curl --data "name=foo" --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects"
-```
-
-##### Post data using JSON content
-
-> **Note:** In this example we create a new group. Watch carefully the single
-and double quotes.
-
-```bash
-curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --header "Content-Type: application/json" --data '{"path": "my-group", "name": "My group"}' https://gitlab.example.com/api/v4/groups
-```
-
-##### Post data using form-data
-
-Instead of using JSON or urlencode you can use multipart/form-data which
-properly handles data encoding:
-
-```bash
-curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --form "title=ssh-key" --form "key=ssh-rsa AAAAB3NzaC1yc2EA..." https://gitlab.example.com/api/v4/users/25/keys
-```
-
-The above example is run by and administrator and will add an SSH public key
-titled ssh-key to user's account which has an id of 25.
-
-##### Escape special characters
-
-Spaces or slashes (`/`) may sometimes result to errors, thus it is recommended
-to escape them when possible. In the example below we create a new issue which
-contains spaces in its title. Observe how spaces are escaped using the `%20`
-ASCII code.
-
-```bash
-curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/42/issues?title=Hello%20Dude"
-```
-
-Use `%2F` for slashes (`/`).
-
-##### Pass arrays to API calls
-
-The GitLab API sometimes accepts arrays of strings or integers. For example, to
-restrict the sign-up e-mail domains of a GitLab instance to `*.example.com` and
-`example.net`, you would do something like this:
-
-```bash
-curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --data "domain_whitelist[]=*.example.com" --data "domain_whitelist[]=example.net" https://gitlab.example.com/api/v4/application/settings
-```
-
-[cURL]: http://curl.haxx.se/ "cURL website"
-[single spaces]: http://www.slate.com/articles/technology/technology/2011/01/space_invaders.html
-[gfm]: http://docs.gitlab.com/ce/user/markdown.html#newlines "GitLab flavored markdown documentation"
-[ce-1242]: https://gitlab.com/gitlab-org/gitlab-ce/issues/1242
-[doc-restart]: ../administration/restart_gitlab.md "GitLab restart documentation"
+redirect_to: 'documentation/styleguide.md'
+---
diff --git a/doc/development/img/manual_build_docs.png b/doc/development/documentation/img/manual_build_docs.png
index 615facabb5f..615facabb5f 100644
--- a/doc/development/img/manual_build_docs.png
+++ b/doc/development/documentation/img/manual_build_docs.png
diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md
new file mode 100644
index 00000000000..f5cdd310f6f
--- /dev/null
+++ b/doc/development/documentation/index.md
@@ -0,0 +1,557 @@
+---
+description: Learn how to contribute to GitLab Documentation.
+---
+
+# GitLab Documentation guidelines
+
+  - **General Documentation**: written by the [developers responsible by creating features](#contributing-to-docs). Should be submitted in the same merge request containing code. Feature proposals (by GitLab contributors) should also be accompanied by its respective documentation. They can be later improved by PMs and Technical Writers.
+  - **[Technical Articles](#technical-articles)**: written by any [GitLab Team](https://about.gitlab.com/team/) member, GitLab contributors, or [Community Writers](https://about.gitlab.com/handbook/product/technical-writing/community-writers/).
+  - **Indexes per topic**: initially prepared by the Technical Writing Team, and kept up-to-date by developers and PMs in the same merge request containing code. They gather all resources for that topic in a single page (user and admin documentation, articles, and third-party docs).
+
+## Contributing to docs
+
+Whenever a feature is changed, updated, introduced, or deprecated, the merge
+request introducing these changes must be accompanied by the documentation
+(either updating existing ones or creating new ones). This is also valid when
+changes are introduced to the UI.
+
+The one responsible for writing the first piece of documentation is the developer who
+wrote the code. It's the job of the Product Manager to ensure all features are
+shipped with its docs, whether is a small or big change. At the pace GitLab evolves,
+this is the only way to keep the docs up-to-date. If you have any questions about it,
+ask a Technical Writer. Otherwise, when your content is ready, assign one of
+them to review it for you.
+
+We use the [monthly release blog post](https://about.gitlab.com/handbook/marketing/blog/release-posts/#monthly-releases) as a changelog checklist to ensure everything
+is documented.
+
+Whenever you submit a merge request for the documentation, use the documentation MR description template.
+
+Please check the [documentation workflow](https://about.gitlab.com/handbook/product/technical-writing/workflow/) before getting started.
+
+## Documentation structure
+
+- Overview and use cases: what it is, why it is necessary, why one would use it
+- Requirements: what do we need to get started
+- Tutorial: how to set it up, how to use it
+
+Always link a new document from its topic-related index, otherwise, it will
+not be included it in the documentation site search.
+
+_Note: to be extended._
+
+### Feature overview and use cases
+
+Every major feature (regardless if present in GitLab Community or Enterprise editions)
+should present, at the beginning of the document, two main sections: **overview** and
+**use cases**. Every GitLab EE-only feature should also contain these sections.
+
+**Overview**: as the name suggests, the goal here is to provide an overview of the feature.
+Describe what is it, what it does, why it is important/cool/nice-to-have,
+what problem it solves, and what you can do with this feature that you couldn't
+do before.
+
+**Use cases**: provide at least two, ideally three, use cases for every major feature.
+You should answer this question: what can you do with this feature/change? Use cases
+are examples of how this feature or change can be used in real life.
+
+Examples:
+- CE and EE: [Issues](../user/project/issues/index.md#use-cases)
+- CE and EE: [Merge Requests](../user/project/merge_requests/index.md#overview)
+- EE-only: [Geo](https://docs.gitlab.com/ee/gitlab-geo/README.html#overview)
+- EE-only: [Jenkins integration](https://docs.gitlab.com/ee/integration/jenkins.md#overview)
+
+Note that if you don't have anything to add between the doc title (`<h1>`) and
+the header `## Overview`, you can omit the header, but keep the content of the
+overview there.
+
+> **Overview** and **use cases** are required to **every** Enterprise Edition feature,
+and for every **major** feature present in Community Edition.
+
+## Markdown and styles
+
+Currently GitLab docs use Redcarpet as [markdown](../user/markdown.md) engine, but there's an [open discussion](https://gitlab.com/gitlab-com/gitlab-docs/issues/50) for implementing Kramdown in the near future.
+
+All the docs follow the [documentation style guidelines](styleguide.md).
+
+## Documentation directory structure
+
+The documentation is structured based on the GitLab UI structure itself,
+separated by [`user`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/user),
+[`administrator`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/administration), and [`contributor`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/development). 
+
+In order to have a [solid site structure](https://searchengineland.com/seo-benefits-developing-solid-site-structure-277456) for our documentation,
+all docs should be linked. Every new document should be cross-linked to its related documentation, and linked from its topic-related index, when existent.
+
+The directories `/workflow/`, `/gitlab-basics/`, `/university/`, and `/articles/` have
+been deprecated and the majority their docs have been moved to their correct location
+in small iterations. Please don't create new docs in these folders.
+
+### Location and naming documents
+
+The documentation hierarchy can be vastly improved by providing a better layout
+and organization of directories.
+
+Having a structured document layout, we will be able to have meaningful URLs
+like `docs.gitlab.com/user/project/merge_requests/index.html`. With this pattern,
+you can immediately tell that you are navigating a user related documentation
+and is about the project and its merge requests.
+
+Do not create summaries of similar types of content (e.g. an index of all articles, videos, etc.),
+rather organize content by its subject (e.g. everything related to CI goes together)
+and cross-link between any related content.
+
+The table below shows what kind of documentation goes where.
+
+| Directory | What belongs here |
+| --------- | -------------- |
+| `doc/user/` | User related documentation. Anything that can be done within the GitLab UI goes here including `/admin`. |
+| `doc/administration/`  | Documentation that requires the user to have access to the server where GitLab is installed. The admin settings that can be accessed via GitLab's interface go under `doc/user/admin_area/`. |
+| `doc/api/` | API related documentation. |
+| `doc/development/` | Documentation related to the development of GitLab. Any styleguides should go here. |
+| `doc/legal/` | Legal documents about contributing to GitLab. |
+| `doc/install/`| Probably the most visited directory, since `installation.md` is there. Ideally this should go under `doc/administration/`, but it's best to leave it as-is in order to avoid confusion (still debated though). |
+| `doc/update/` | Same with `doc/install/`. Should be under `administration/`, but this is a well known location, better leave as-is, at least for now. |
+| `doc/topics/` | Indexes per Topic (`doc/topics/topic-name/index.md`): all resources for that topic (user and admin documentation, articles, and third-party docs) |
+
+---
+
+**General rules:**
+
+1. The correct naming and location of a new document, is a combination
+   of the relative URL of the document in question and the GitLab Map design
+   that is used for UX purposes ([source][graffle], [image][gitlab-map]).
+1. When creating a new document and it has more than one word in its name,
+   make sure to use underscores instead of spaces or dashes (`-`). For example,
+   a proper naming would be `import_projects_from_github.md`. The same rule
+   applies to images.
+1. Start a new directory with an `index.md` file.
+1. There are four main directories, `user`, `administration`, `api` and `development`.
+1. The `doc/user/` directory has five main subdirectories: `project/`, `group/`,
+   `profile/`, `dashboard/` and `admin_area/`.
+   1. `doc/user/project/` should contain all project related documentation.
+   1. `doc/user/group/` should contain all group related documentation.
+   1. `doc/user/profile/` should contain all profile related documentation.
+      Every page you would navigate under `/profile` should have its own document,
+      i.e. `account.md`, `applications.md`, `emails.md`, etc.
+   1. `doc/user/dashboard/` should contain all dashboard related documentation.
+   1. `doc/user/admin_area/` should contain all admin related documentation
+      describing what can be achieved by accessing GitLab's admin interface
+      (_not to be confused with `doc/administration` where server access is
+      required_).
+      1. Every category under `/admin/application_settings` should have its
+         own document located at `doc/user/admin_area/settings/`. For example,
+         the **Visibility and Access Controls** category should have a document
+         located at `doc/user/admin_area/settings/visibility_and_access_controls.md`.
+1. The `doc/topics/` directory holds topic-related technical content. Create
+   `doc/topics/topic-name/subtopic-name/index.md` when subtopics become necessary.
+   General user- and admin- related documentation, should be placed accordingly.
+
+If you are unsure where a document should live, you can ping `@axil` or `@marcia` in your
+merge request.
+
+### Changing document location
+
+Changing a document's location is not to be taken lightly. Remember that the
+documentation is available to all installations under `help/` and not only to
+GitLab.com or http://docs.gitlab.com. Make sure this is discussed with the
+Documentation team beforehand.
+
+If you indeed need to change a document's location, do NOT remove the old
+document, but rather replace all of its contents with a new line:
+
+```
+This document was moved to [another location](path/to/new_doc.md).
+```
+
+where `path/to/new_doc.md` is the relative path to the root directory `doc/`.
+
+---
+
+For example, if you were to move `doc/workflow/lfs/lfs_administration.md` to
+`doc/administration/lfs.md`, then the steps would be:
+
+1. Copy `doc/workflow/lfs/lfs_administration.md` to `doc/administration/lfs.md`
+1. Replace the contents of `doc/workflow/lfs/lfs_administration.md` with:
+
+    ```
+    This document was moved to [another location](../../administration/lfs.md).
+    ```
+
+1. Find and replace any occurrences of the old location with the new one.
+   A quick way to find them is to use `git grep`. First go to the root directory
+   where you cloned the `gitlab-ce` repository and then do:
+
+    ```
+    git grep -n "workflow/lfs/lfs_administration"
+    git grep -n "lfs/lfs_administration"
+    ```
+
+NOTE: **Note:**
+If the document being moved has any Disqus comments on it, there are extra steps
+to follow documented just [below](#redirections-for-pages-with-disqus-comments).
+
+Things to note:
+
+- Since we also use inline documentation, except for the documentation itself,
+  the document might also be referenced in the views of GitLab (`app/`) which will
+  render when visiting `/help`, and sometimes in the testing suite (`spec/`).
+- The above `git grep` command will search recursively in the directory you run
+  it in for `workflow/lfs/lfs_administration` and `lfs/lfs_administration`
+  and will print the file and the line where this file is mentioned.
+  You may ask why the two greps. Since we use relative paths to link to
+  documentation, sometimes it might be useful to search a path deeper.
+- The `*.md` extension is not used when a document is linked to GitLab's
+  built-in help page, that's why we omit it in `git grep`.
+- Use the checklist on the documentation MR description template.
+
+#### Alternative redirection method
+
+Alternatively to the method described above, you can simply replace the content
+of the old file with a frontmatter containing a redirect link:
+
+```yaml
+---
+redirect_to: '../path/to/file/README.md'
+---
+```
+
+It supports both full and relative URLs, e.g. `https://docs.gitlab.com/ee/path/to/file.html`, `../path/to/file.html`, `path/to/file.md`. Note that any `*.md` paths will be compiled to `*.html`.
+
+### Redirections for pages with Disqus comments
+
+If the documentation page being relocated already has any Disqus comments,
+we need to preserve the Disqus thread.
+
+Disqus uses an identifier per page, and for docs.gitlab.com, the page identifier
+is configured to be the page URL. Therefore, when we change the document location,
+we need to preserve the old URL as the same Disqus identifier.
+
+To do that, add to the frontmatter the variable `redirect_from`,
+using the old URL as value. For example, let's say I moved the document
+available under `https://docs.gitlab.com/my-old-location/README.html` to a new location,
+`https://docs.gitlab.com/my-new-location/index.html`.
+
+Into the **new document** frontmatter add the following:
+
+```yaml
+---
+redirect_from: 'https://docs.gitlab.com/my-old-location/README.html'
+---
+```
+
+Note: it is necessary to include the file name in the `redirect_from` URL,
+even if it's `index.html` or `README.html`.
+
+## Testing
+
+We treat documentation as code, thus have implemented some testing.
+Currently, the following tests are in place:
+
+1. `docs lint`: Check that all internal (relative) links work correctly and
+   that all cURL examples in API docs use the full switches. It's recommended
+   to [check locally](#previewing-locally) before pushing to GitLab by executing the command
+   `bundle exec nanoc check internal_links` on your local
+   [`gitlab-docs`](https://gitlab.com/gitlab-com/gitlab-docs) directory.
+1. [`ee_compat_check`](../automatic_ce_ee_merge.md#avoiding-ce-gt-ee-merge-conflicts-beforehand) (runs on CE only):
+    When you submit a merge request to GitLab Community Edition (CE),
+    there is this additional job that runs against Enterprise Edition (EE)
+    and checks if your changes can apply cleanly to the EE codebase.
+    If that job fails, read the instructions in the job log for what to do next.
+    As CE is merged into EE once a day, it's important to avoid merge conflicts.
+    Submitting an EE-equivalent merge request cherry-picking all commits from CE to EE is
+    essential to avoid them.
+
+## Branch naming
+
+If your contribution contains **only** documentation changes, you can speed up
+the CI process by following some branch naming conventions. You have three
+choices:
+
+| Branch name | Valid example |
+| ----------- | ------------- |
+| Starting with `docs/` | `docs/update-api-issues`     |
+| Starting with `docs-` | `docs-update-api-issues`     |
+| Ending in `-docs`     | `123-update-api-issues-docs` |
+
+If your branch name matches any of the above, it will run only the docs
+tests. If it doesn't, the whole test suite will run (including docs).
+
+## Merge requests for GitLab documentation
+
+Before getting started, make sure you read the introductory section
+"[contributing to docs](#contributing-to-docs)" above and the
+[tech writing workflow](https://about.gitlab.com/handbook/product/technical-writing/workflow/)
+for GitLab Team members.
+
+- Use the current [merge request description template](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.gitlab/merge_request_templates/Documentation.md)
+- Use the correct [branch name](#branch-naming)
+- Label the MR `Documentation`
+- Assign the correct milestone (see note below)
+
+
+NOTE: **Note:**
+If the release version you want to add the documentation to has already been
+frozen or released, use the label `Pick into X.Y` to get it merged into
+the correct release. Avoid picking into a past release as much as you can, as
+it increases the work of the release managers.
+
+### Cherry-picking from CE to EE
+
+As we have the `master` branch of CE merged into EE once a day, it's common to
+run into merge conflicts. To avoid them, we [test for merge conflicts against EE](#testing)
+with the `ee-compat-check` job, and use the following method of creating equivalent
+branches for CE and EE.
+
+Follow this [method for cherry-picking from CE to EE](../automatic_ce_ee_merge.md#cherry-picking-from-ce-to-ee), with a few adjustments:
+
+- Create the [CE branch](#branch-naming) starting with `docs-`,
+  e.g.: `git checkout -b docs-example`
+- Create the EE-equivalent branch ending with `-ee`, e.g.,
+  `git checkout -b docs-example-ee`
+- Once all the jobs are passing in CE and EE, and you've addressed the
+feedback from your own team, assign the CE MR to a technical writer for review
+- When both MRs are ready, the EE merge request will be merged first, and the
+CE-equivalent will be merged next.
+- Note that the review will occur only in the CE MR, as the EE MR
+contains the same commits as the CE MR.
+- If you have a few more changes that apply to the EE-version only, you can submit
+a couple more commits to the EE branch, but ask the reviewer to review the EE merge request
+additionally to the CE MR. If there are many EE-only changes though, start a new MR
+to EE only.
+
+## Previewing the changes live
+
+NOTE: **Note:**
+To preview your changes to documentation locally, follow this
+[development guide](https://gitlab.com/gitlab-com/gitlab-docs/blob/master/README.md#development).
+
+The live preview is currently enabled for the following projects:
+
+- https://gitlab.com/gitlab-org/gitlab-ce
+- https://gitlab.com/gitlab-org/gitlab-ee
+- https://gitlab.com/gitlab-org/gitlab-runner
+
+If your branch contains only documentation changes, you can use
+[special branch names](#branch-naming) to avoid long running pipelines.
+
+For [docs-only changes](#branch-naming), the review app is run automatically.
+For all other branches, you can use the manual `review-docs-deploy-manual` job
+in your merge request. You will need at least Maintainer permissions to be able
+to run it. In the mini pipeline graph, you should see an `>>` icon. Clicking on it will
+reveal the `review-docs-deploy-manual` job. Hit the play button for the job to start.
+
+![Manual trigger a docs build](img/manual_build_docs.png)
+
+NOTE: **Note:**
+You will need to push a branch to those repositories, it doesn't work for forks.
+
+The `review-docs-deploy*` job will:
+
+1. Create a new branch in the [gitlab-docs](https://gitlab.com/gitlab-com/gitlab-docs)
+   project named after the scheme: `$DOCS_GITLAB_REPO_SUFFIX-$CI_ENVIRONMENT_SLUG`,
+   where `DOCS_GITLAB_REPO_SUFFIX` is the suffix for each product, e.g, `ce` for
+   CE, etc.
+1. Trigger a cross project pipeline and build the docs site with your changes
+
+After a few minutes, the Review App will be deployed and you will be able to
+preview the changes. The docs URL can be found in two places:
+
+- In the merge request widget
+- In the output of the `review-docs-deploy*` job, which also includes the
+  triggered pipeline so that you can investigate whether something went wrong
+
+In case the Review App URL returns 404, follow these steps to debug:
+
+1. **Did you follow the URL from the merge request widget?** If yes, then check if
+   the link is the same as the one in the job output.
+1. **Did you follow the URL from the job output?** If yes, then it means that
+   either the site is not yet deployed or something went wrong with the remote
+   pipeline. Give it a few minutes and it should appear online, otherwise you
+   can check the status of the remote pipeline from the link in the job output.
+   If the pipeline failed or got stuck, drop a line in the `#docs` chat channel.
+
+TIP: **Tip:**
+Someone that has no merge rights to the CE/EE projects (think of forks from
+contributors) will not be able to run the manual job. In that case, you can
+ask someone from the GitLab team who has the permissions to do that for you.
+
+NOTE: **Note:**
+Make sure that you always delete the branch of the merge request you were
+working on. If you don't, the remote docs branch won't be removed either,
+and the server where the Review Apps are hosted will eventually be out of
+disk space.
+
+### Technical aspects
+
+If you want to know the hot details, here's what's really happening:
+
+1. You manually run the `review-docs-deploy` job in a CE/EE merge request.
+1. The job runs the [`scripts/trigger-build-docs`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/scripts/trigger-build-docs)
+   script with the `deploy` flag, which in turn:
+   1. Takes your branch name and applies the following:
+      - The slug of the branch name is used to avoid special characters since
+        ultimately this will be used by NGINX.
+      - The `preview-` prefix is added to avoid conflicts if there's a remote branch
+        with the same name that you created in the merge request.
+      - The final branch name is truncated to 42 characters to avoid filesystem
+        limitations with long branch names (> 63 chars).
+   1. The remote branch is then created if it doesn't exist (meaning you can
+      re-run the manual job as many times as you want and this step will be skipped).
+   1. A new cross-project pipeline is triggered in the docs project.
+   1. The preview URL is shown both at the job output and in the merge request
+      widget. You also get the link to the remote pipeline.
+1. In the docs project, the pipeline is created and it
+   [skips the test jobs](https://gitlab.com/gitlab-com/gitlab-docs/blob/8d5d5c750c602a835614b02f9db42ead1c4b2f5e/.gitlab-ci.yml#L50-55)
+   to lower the build time.
+1. Once the docs site is built, the HTML files are uploaded as artifacts.
+1. A specific Runner tied only to the docs project, runs the Review App job
+   that downloads the artifacts and uses `rsync` to transfer the files over
+   to a location where NGINX serves them.
+
+The following GitLab features are used among others:
+
+- [Manual actions](../../ci/yaml/README.md#manual-actions)
+- [Multi project pipelines](https://docs.gitlab.com/ee/ci/multi_project_pipeline_graphs.html)
+- [Review Apps](../../ci/review_apps/index.md)
+- [Artifacts](../../ci/yaml/README.md#artifacts)
+- [Specific Runner](../../ci/runners/README.md#locking-a-specific-runner-from-being-enabled-for-other-projects)
+
+## GitLab `/help`
+
+Every GitLab instance includes the documentation, which is available from `/help`
+(`http://my-instance.com/help`), e.g., <https://gitlab.com/help>.
+
+When you're building a new feature, you may need to link the documentation
+from GitLab, the application. This is normally done in files inside the
+`app/views/` directory with the help of the `help_page_path` helper method.
+
+In its simplest form, the HAML code to generate a link to the `/help` page is:
+
+```haml
+= link_to 'Help page', help_page_path('user/permissions')
+```
+
+The `help_page_path` contains the path to the document you want to link to with
+the following conventions:
+
+- it is relative to the `doc/` directory in the GitLab repository
+- the `.md` extension must be omitted
+- it must not end with a slash (`/`)
+
+Below are some special cases where should be used depending on the context.
+You can combine one or more of the following:
+
+1. **Linking to an anchor link.** Use `anchor` as part of the `help_page_path`
+   method:
+
+    ```haml
+    = link_to 'Help page', help_page_path('user/permissions', anchor: 'anchor-link')
+    ```
+
+1. **Opening links in a new tab.** This should be the default behavior:
+
+    ```haml
+    = link_to 'Help page', help_page_path('user/permissions'), target: '_blank'
+    ```
+
+1. **Linking to a circle icon.** Usually used in settings where a long
+   description cannot be used, like near checkboxes. You can basically use
+   any font awesome icon, but prefer the `question-circle`:
+
+    ```haml
+    = link_to icon('question-circle'), help_page_path('user/permissions')
+    ```
+
+1. **Using a button link.** Useful in places where text would be out of context
+   with the rest of the page layout:
+
+    ```haml
+    = link_to 'Help page', help_page_path('user/permissions'),  class: 'btn btn-info'
+    ```
+
+1. **Using links inline of some text.**
+
+    ```haml
+    Description to #{link_to 'Help page', help_page_path('user/permissions')}.
+    ```
+
+1. **Adding a period at the end of the sentence.** Useful when you don't want
+   the period to be part of the link:
+
+    ```haml
+    = succeed '.' do
+      Learn more in the
+      = link_to 'Help page', help_page_path('user/permissions')
+    ```
+
+## General Documentation vs Technical Articles
+
+### General documentation
+
+General documentation is categorized by _User_, _Admin_, and _Contributor_, and describe what that feature is, what it does, and its available settings.
+
+### Technical Articles
+
+Technical articles replace technical content that once lived in the [GitLab Blog](https://about.gitlab.com/blog/), where they got out-of-date and weren't easily found.
+
+They are topic-related documentation, written with an user-friendly approach and language, aiming to provide the community with guidance on specific processes to achieve certain objectives.
+
+A technical article guides users and/or admins to achieve certain objectives (within guides and tutorials), or provide an overview of that particular topic or feature (within technical overviews). It can also describe the use, implementation, or integration of third-party tools with GitLab.
+
+They should be placed in a new directory named `/article-title/index.md` under a topic-related folder, and their images should be placed in `/article-title/img/`. For example, a new article on GitLab Pages should be placed in `doc/user/project/pages/article-title/` and a new article on GitLab CI/CD should be placed in `doc/ci/examples/article-title/`.
+
+#### Types of Technical Articles
+
+- **User guides**: technical content to guide regular users from point A to point B
+- **Admin guides**: technical content to guide administrators of GitLab instances from point A to point B
+- **Technical Overviews**: technical content describing features, solutions, and third-party integrations
+- **Tutorials**: technical content provided step-by-step on how to do things, or how to reach very specific objectives
+
+#### Understanding guides, tutorials, and technical overviews
+
+Suppose there's a process to go from point A to point B in 5 steps: `(A) 1 > 2 > 3 > 4 > 5 (B)`.
+
+A **guide** can be understood as a description of certain processes to achieve a particular objective. A guide brings you from A to B describing the characteristics of that process, but not necessarily going over each step. It can mention, for example, steps 2 and 3, but does not necessarily explain how to accomplish them.
+
+- Live example: "[Static sites and GitLab Pages domains (Part 1)](../user/project/pages/getting_started_part_one.md) to [Creating and Tweaking GitLab CI/CD for GitLab Pages (Part 4)](../../user/project/pages/getting_started_part_four.md)"
+
+A **tutorial** requires a clear **step-by-step** guidance to achieve a singular objective. It brings you from A to B, describing precisely all the necessary steps involved in that process, showing each of the 5 steps to go from A to B.
+It does not only describes steps 2 and 3, but also shows you how to accomplish them.
+
+- Live example (on the blog): [Hosting on GitLab.com with GitLab Pages](https://about.gitlab.com/2016/04/07/gitlab-pages-setup/)
+
+A **technical overview** is a description of what a certain feature is, and what it does, but does not walk
+through the process of how to use it systematically.
+
+- Live example (on the blog): [GitLab Workflow, an overview](https://about.gitlab.com/2016/10/25/gitlab-workflow-an-overview/)
+
+#### Special format
+
+Every **Technical Article** contains a frontmatter at the beginning of the doc
+with the following information:
+
+- **Type of article** (user guide, admin guide, technical overview, tutorial)
+- **Knowledge level** expected from the reader to be able to follow through (beginner, intermediate, advanced)
+- **Author's name** and **GitLab.com handle**
+- **Publication date** (ISO format YYYY-MM-DD)
+
+For example:
+
+
+```yaml
+---
+author: John Doe
+author_gitlab: johnDoe
+level: beginner
+article_type: user guide
+date: 2017-02-01
+---
+```
+
+#### Technical Articles - Writing Method
+
+Use the [writing method](https://about.gitlab.com/handbook/product/technical-writing/#writing-method) defined by the Technical Writing team.
+
+[gitlab-map]: https://gitlab.com/gitlab-org/gitlab-design/raw/master/production/resources/gitlab-map.png
+[graffle]: https://gitlab.com/gitlab-org/gitlab-design/blob/d8d39f4a87b90fb9ae89ca12dc565347b4900d5e/production/resources/gitlab-map.graffle
diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md
new file mode 100644
index 00000000000..a315cfdc116
--- /dev/null
+++ b/doc/development/documentation/styleguide.md
@@ -0,0 +1,513 @@
+---
+description: 'Writing styles, markup, formatting, and reusing regular expressions throughout the GitLab Documentation.'
+---
+
+# Documentation style guidelines
+
+The documentation style guide defines the markup structure used in
+GitLab documentation. Check the
+[documentation guidelines](index.md) for general development instructions.
+
+Check the GitLab handbook for the [writing styles guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines).
+
+## Text
+
+- Split up long lines (wrap text), this makes it much easier to review and edit. Only
+  double line breaks are shown as a full line break in [GitLab markdown][gfm].
+  80-100 characters is a good line length
+- Make sure that the documentation is added in the correct
+  [directory](index.md#documentation-directory-structure) and that
+  there's a link to it somewhere useful
+- Do not duplicate information
+- Be brief and clear
+- Unless there's a logical reason not to, add documents in alphabetical order
+- Write in US English
+- Use [single spaces][] instead of double spaces
+- Jump a line between different markups (e.g., after every paragraph, header, list, etc)
+- Capitalize "G" and "L" in GitLab
+- Use sentence case for titles, headings, labels, menu items, and buttons.
+- Use title case when referring to [features](https://about.gitlab.com/features/) or
+[products](https://about.gitlab.com/pricing/) (e.g., GitLab Runner, Geo,
+Issue Boards, GitLab Core, Git, Prometheus, Kubernetes, etc), and methods or methodologies
+(e.g., Continuous Integration, Continuous Deployment, Scrum, Agile, etc). Note that
+some features are also objects (e.g. "Merge Requests" and "merge requests").
+
+## Formatting
+
+- Use double asterisks (`**`) to mark a word or text in bold (`**bold**`)
+- Use undescore (`_`) for text in italics (`_italic_`)
+- Jump a line between different markups, for example:
+
+    ```md
+    ## Header
+
+    Paragraph.
+
+    - List item
+    - List item
+    ```
+
+### Punctuation
+
+For punctuation rules, please refer to the [GitLab UX guide](https://design.gitlab.com/content/punctuation/).
+
+### Ordered and unordered lists
+
+- Use dashes (`-`) for unordered lists instead of asterisks (`*`)
+- Use the number one (`1`) for ordered lists
+- For punctuation in bullet lists, please refer to the [GitLab UX guide](https://design.gitlab.com/content/punctuation/)
+
+## Headings
+
+- Add **only one H1** in each document, by adding `#` at the beginning of
+  it (when using markdown). The `h1` will be the document `<title>`.
+- For subheadings, use `##`, `###` and so on
+- Avoid putting numbers in headings. Numbers shift, hence documentation anchor
+  links shift too, which eventually leads to dead links. If you think it is
+  compelling to add numbers in headings, make sure to at least discuss it with
+  someone in the Merge Request
+- [Avoid using symbols and special chars](https://gitlab.com/gitlab-com/gitlab-docs/issues/84)
+  in headers. Whenever possible, they should be plain and short text.
+- Avoid adding things that show ephemeral statuses. For example, if a feature is
+  considered beta or experimental, put this info in a note, not in the heading.
+- When introducing a new document, be careful for the headings to be
+  grammatically and syntactically correct. Mention one or all
+  of the following GitLab members for a review: `@axil` or `@marcia`.
+  This is to ensure that no document with wrong heading is going
+  live without an audit, thus preventing dead links and redirection issues when
+  corrected
+- Leave exactly one new line after a heading
+
+## Links
+
+- Use the regular inline link markdown markup `[Text](https://example.com)`.
+  It's easier to read, review, and maintain.
+- If there's a link that repeats several times through the same document,
+  you can use `[Text][identifier]` and at the bottom of the section or the
+  document add: `[identifier]: https://example.com`, in which case, we do
+  encourage you to also add an alternative text: `[identifier]: https://example.com "Alternative text"` that appears when hovering your mouse on a link.
+- To link to internal documentation, use relative links, not full URLs. Use `../` to
+  navigate tp high-level directories, and always add the file name `file.md` at the
+  end of the link with the `.md` extension, not `.html`.
+  Example: instead of `[text](../../merge_requests/)`, use
+  `[text](../../merge_requests/index.md)` or, `[text](../../ci/README.md)`, or,
+  for anchor links, `[text](../../ci/README.md#examples)`.
+  Using the markdown extension is necessary for the [`/help`](index.md#gitlab-help)
+  section of GitLab.
+- To link from CE to EE-only documentation, use the EE-only doc full URL.
+- Use [meaningful anchor texts](https://www.futurehosting.com/blog/links-should-have-meaningful-anchor-text-heres-why/).
+  E.g., instead of writing something like `Read more about GitLab Issue Boards [here](LINK)`,
+  write `Read more about [GitLab Issue Boards](LINK)`.
+
+## Navigation
+
+To indicate the steps of navigation through the UI:
+
+- Use the exact word as shown in the UI, including any capital letters as-is
+- Use bold text for navigation items and the char `>` as separator
+(e.g., `Navigate to your project's **Settings > CI/CD**` )
+- If there are any expandable menus, make sure to mention that the user
+needs to expand the tab to find the settings you're referring to
+
+## Images
+
+- Place images in a separate directory named `img/` in the same directory where
+  the `.md` document that you're working on is located. Always prepend their
+  names with the name of the document that they will be included in. For
+  example, if there is a document called `twitter.md`, then a valid image name
+  could be `twitter_login_screen.png`. [**Exception**: images for
+  [articles](index.md#technical-articles) should be
+  put in a directory called `img` underneath `/articles/article_title/img/`, therefore,
+  there's no need to prepend the document name to their filenames.]
+- Images should have a specific, non-generic name that will differentiate them.
+- Keep all file names in lower case.
+- Consider using PNG images instead of JPEG.
+- Compress all images with <https://tinypng.com/> or similar tool.
+- Compress gifs with <https://ezgif.com/optimize> or similar tool.
+- Images should be used (only when necessary) to _illustrate_ the description
+of a process, not to _replace_ it.
+
+Inside the document:
+
+- The Markdown way of using an image inside a document is:
+  `![Proper description what the image is about](img/document_image_title.png)`
+- Always use a proper description for what the image is about. That way, when a
+  browser fails to show the image, this text will be used as an alternative
+  description
+- If there are consecutive images with little text between them, always add
+  three dashes (`---`) between the image and the text to create a horizontal
+  line for better clarity
+- If a heading is placed right after an image, always add three dashes (`---`)
+  between the image and the heading
+
+## Alert boxes
+
+Whenever you want to call the attention to a particular sentence,
+use the following markup for highlighting.
+
+_Note that the alert boxes only work for one paragraph only. Multiple paragraphs,
+lists, headers, etc will not render correctly._
+
+### Note
+
+```md
+NOTE: **Note:**
+This is something to note.
+```
+
+How it renders in docs.gitlab.com:
+
+NOTE: **Note:**
+This is something to note.
+
+### Tip
+
+```md
+TIP: **Tip:**
+This is a tip.
+```
+
+How it renders in docs.gitlab.com:
+
+TIP: **Tip:**
+This is a tip.
+
+### Caution
+
+```md
+CAUTION: **Caution:**
+This is something to be cautious about.
+```
+
+How it renders in docs.gitlab.com:
+
+CAUTION: **Caution:**
+This is something to be cautious about.
+
+### Danger
+
+```md
+DANGER: **Danger:**
+This is a breaking change, a bug, or something very important to note.
+```
+
+How it renders in docs.gitlab.com:
+
+DANGER: **Danger:**
+This is a breaking change, a bug, or something very important to note.
+
+## Blockquotes
+
+For highlighting a text within a blue blockquote, use this format:
+
+```md
+> This is a blockquote.
+```
+
+which renders in docs.gitlab.com to:
+
+> This is a blockquote.
+
+If the text spans across multiple lines it's OK to split the line.
+
+## Specific sections and terms
+
+To mention and/or reference specific terms in GitLab, please follow the styles
+below.
+
+### GitLab versions and tiers
+
+- Every piece of documentation that comes with a new feature should declare the
+  GitLab version that feature got introduced. Right below the heading add a
+  note:
+
+    ```md
+    > Introduced in GitLab 8.3.
+    ```
+
+- Whenever possible, every feature should have a link to the MR, issue, or epic that introduced it.
+  The above note would be then transformed to:
+
+    ```md
+    > [Introduced][ce-1242] in GitLab 8.3.
+    ```
+
+    , where the [link identifier](#links) is named after the repository (CE) and
+    the MR number.
+
+- If the feature is only available in GitLab Enterprise Edition, don't forget to mention
+  the [paid tier](https://about.gitlab.com/handbook/marketing/product-marketing/#tiers)
+  the feature is available in:
+
+    ```md
+    > [Introduced][ee-1234] in [GitLab Starter](https://about.gitlab.com/pricing/) 8.3.
+    ```
+
+### Product badges
+
+When a feature is available in EE-only tiers, add the corresponding tier according to the
+feature availability:
+
+- For GitLab Starter and GitLab.com Bronze: `**[STARTER]**`
+- For GitLab Premium and GitLab.com Silver: `**[PREMIUM]**`
+- For GitLab Ultimate and GitLab.com Gold: `**[ULTIMATE]**`
+- For GitLab Core and GitLab.com Free: `**[CORE]**`
+
+To exclude GitLab.com tiers (when the feature is not available in GitLab.com), add the
+keyword "only":
+
+- For GitLab Starter: `**[STARTER ONLY]**`
+- For GitLab Premium: `**[PREMIUM ONLY]**`
+- For GitLab Ultimate: `**[ULTIMATE ONLY]**`
+- For GitLab Core: `**[CORE ONLY]**`
+
+The tier should be ideally added to headers, so that the full badge will be displayed.
+But it can be also mentioned from paragraphs, list items, and table cells. For these cases,
+the tier mention will be represented by an orange question mark.
+E.g., `**[STARTER]**` renders **[STARTER]**, `**[STARTER ONLY]**` renders **[STARTER ONLY]**.
+
+The absence of tiers' mentions mean that the feature is available in GitLab Core,
+GitLab.com Free, and higher tiers.
+
+#### How it works
+
+Introduced by [!244](https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/244),
+the special markup `**[STARTER]**` will generate a `span` element to trigger the
+badges and tooltips (`<span class="badge-trigger starter">`). When the keyword
+"only" is added, the corresponding GitLab.com badge will not be displayed.
+
+### GitLab Restart
+
+There are many cases that a restart/reconfigure of GitLab is required. To
+avoid duplication, link to the special document that can be found in
+[`doc/administration/restart_gitlab.md`][doc-restart]. Usually the text will
+read like:
+
+  ```
+  Save the file and [reconfigure GitLab](../../administration/restart_gitlab.md)
+  for the changes to take effect.
+  ```
+
+If the document you are editing resides in a place other than the GitLab CE/EE
+`doc/` directory, instead of the relative link, use the full path:
+`http://docs.gitlab.com/ce/administration/restart_gitlab.html`.
+Replace `reconfigure` with `restart` where appropriate.
+
+### Installation guide
+
+**Ruby:**
+In [step 2 of the installation guide](../../install/installation.md#2-ruby),
+we install Ruby from source. Whenever there is a new version that needs to
+be updated, remember to change it throughout the codeblock and also replace
+the sha256sum (it can be found in the [downloads page][ruby-dl] of the Ruby
+website).
+
+[ruby-dl]: https://www.ruby-lang.org/en/downloads/ "Ruby download website"
+
+### Configuration documentation for source and Omnibus installations
+
+GitLab currently officially supports two installation methods: installations
+from source and Omnibus packages installations.
+
+Whenever there is a setting that is configurable for both installation methods,
+prefer to document it in the CE docs to avoid duplication.
+
+Configuration settings include:
+
+- settings that touch configuration files in `config/`
+- NGINX settings and settings in `lib/support/` in general
+
+When there is a list of steps to perform, usually that entails editing the
+configuration file and reconfiguring/restarting GitLab. In such case, follow
+the style below as a guide:
+
+```md
+**For Omnibus installations**
+
+1. Edit `/etc/gitlab/gitlab.rb`:
+
+    ```ruby
+    external_url "https://gitlab.example.com"
+    ```
+
+1. Save the file and [reconfigure] GitLab for the changes to take effect.
+
+---
+
+**For installations from source**
+
+1. Edit `config/gitlab.yml`:
+
+    ```yaml
+    gitlab:
+      host: "gitlab.example.com"
+    ```
+
+1. Save the file and [restart] GitLab for the changes to take effect.
+
+
+[reconfigure]: path/to/administration/restart_gitlab.md#omnibus-gitlab-reconfigure
+[restart]: path/to/administration/restart_gitlab.md#installations-from-source
+```
+
+In this case:
+
+- before each step list the installation method is declared in bold
+- three dashes (`---`) are used to create a horizontal line and separate the
+  two methods
+- the code blocks are indented one or more spaces under the list item to render
+  correctly
+- different highlighting languages are used for each config in the code block
+- the [references](#references) guide is used for reconfigure/restart
+
+### Fake tokens
+
+There may be times where a token is needed to demonstrate an API call using
+cURL or a variable used in CI. It is strongly advised not to use real
+tokens in documentation even if the probability of a token being exploited is
+low.
+
+You can use the following fake tokens as examples.
+
+|     **Token type**    |           **Token value**         |
+| --------------------- | --------------------------------- |
+| Private user token    | `9koXpg98eAheJpvBs5tK`            |
+| Personal access token | `n671WNGecHugsdEDPsyo`            |
+| Application ID        | `2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6` |
+| Application secret    | `04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df` |
+| Secret CI variable    | `Li8j-mLUVA3eZYjPfd_H`            |
+| Specific Runner token | `yrnZW46BrtBFqM7xDzE7dddd`        |
+| Shared Runner token   | `6Vk7ZsosqQyfreAxXTZr`            |
+| Trigger token         | `be20d8dcc028677c931e04f3871a9b`  |
+| Webhook secret token  | `6XhDroRcYPM5by_h-HLY`            |
+| Health check token    | `Tu7BgjR9qeZTEyRzGG2P`            |
+| Request profile token | `7VgpS4Ax5utVD2esNstz`            |
+
+### API
+
+Here is a list of must-have items. Use them in the exact order that appears
+on this document. Further explanation is given below.
+
+- Every method must have the REST API request. For example:
+
+    ```
+    GET /projects/:id/repository/branches
+    ```
+
+- Every method must have a detailed
+  [description of the parameters](#method-description).
+- Every method must have a cURL example.
+- Every method must have a response body (in JSON format).
+
+#### Method description
+
+Use the following table headers to describe the methods. Attributes should
+always be in code blocks using backticks (``` ` ```).
+
+```
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+```
+
+Rendered example:
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `user`  | string | yes | The GitLab username |
+
+#### cURL commands
+
+- Use `https://gitlab.example.com/api/v4/` as an endpoint.
+- Wherever needed use this personal access token: `9koXpg98eAheJpvBs5tK`.
+- Always put the request first. `GET` is the default so you don't have to
+  include it.
+- Use double quotes to the URL when it includes additional parameters.
+- Prefer to use examples using the personal access token and don't pass data of
+  username and password.
+
+| Methods | Description |
+| ------- | ----------- |
+| `-H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK"` | Use this method as is, whenever authentication needed |
+| `-X POST`   | Use this method when creating new objects |
+| `-X PUT`    | Use this method when updating existing objects |
+| `-X DELETE` | Use this method when removing existing objects |
+
+#### cURL Examples
+
+Below is a set of [cURL][] examples that you can use in the API documentation.
+
+##### Simple cURL command
+
+Get the details of a group:
+
+```bash
+curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/gitlab-org
+```
+
+##### cURL example with parameters passed in the URL
+
+Create a new project under the authenticated user's namespace:
+
+```bash
+curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects?name=foo"
+```
+
+##### Post data using cURL's --data
+
+Instead of using `-X POST` and appending the parameters to the URI, you can use
+cURL's `--data` option. The example below will create a new project `foo` under
+the authenticated user's namespace.
+
+```bash
+curl --data "name=foo" --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects"
+```
+
+##### Post data using JSON content
+
+> **Note:** In this example we create a new group. Watch carefully the single
+and double quotes.
+
+```bash
+curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --header "Content-Type: application/json" --data '{"path": "my-group", "name": "My group"}' https://gitlab.example.com/api/v4/groups
+```
+
+##### Post data using form-data
+
+Instead of using JSON or urlencode you can use multipart/form-data which
+properly handles data encoding:
+
+```bash
+curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --form "title=ssh-key" --form "key=ssh-rsa AAAAB3NzaC1yc2EA..." https://gitlab.example.com/api/v4/users/25/keys
+```
+
+The above example is run by and administrator and will add an SSH public key
+titled ssh-key to user's account which has an id of 25.
+
+##### Escape special characters
+
+Spaces or slashes (`/`) may sometimes result to errors, thus it is recommended
+to escape them when possible. In the example below we create a new issue which
+contains spaces in its title. Observe how spaces are escaped using the `%20`
+ASCII code.
+
+```bash
+curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/42/issues?title=Hello%20Dude"
+```
+
+Use `%2F` for slashes (`/`).
+
+##### Pass arrays to API calls
+
+The GitLab API sometimes accepts arrays of strings or integers. For example, to
+restrict the sign-up e-mail domains of a GitLab instance to `*.example.com` and
+`example.net`, you would do something like this:
+
+```bash
+curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --data "domain_whitelist[]=*.example.com" --data "domain_whitelist[]=example.net" https://gitlab.example.com/api/v4/application/settings
+```
+
+[cURL]: http://curl.haxx.se/ "cURL website"
+[single spaces]: http://www.slate.com/articles/technology/technology/2011/01/space_invaders.html
+[gfm]: http://docs.gitlab.com/ce/user/markdown.html#newlines "GitLab flavored markdown documentation"
+[ce-1242]: https://gitlab.com/gitlab-org/gitlab-ce/issues/1242
+[doc-restart]: ../../administration/restart_gitlab.md "GitLab restart documentation"
diff --git a/doc/development/ee_features.md b/doc/development/ee_features.md
index fea92e740cb..7f061d06da8 100644
--- a/doc/development/ee_features.md
+++ b/doc/development/ee_features.md
@@ -33,6 +33,29 @@ rest of the code should be as close to the CE files as possible.
 
 [single code base]: https://gitlab.com/gitlab-org/gitlab-ee/issues/2952#note_41016454
 
+### EE-specific comments
+
+When complete separation can't be achieved with the `ee/` directory, you can wrap
+code in EE specific comments to designate the difference from CE/EE and add
+some context for someone resolving a conflict.
+
+```rb
+# EE-specific start
+stub_licensed_features(variable_environment_scope: true)
+# EE specific end
+```
+
+```haml
+-# EE-specific start
+= render 'ci/variables/environment_scope', form_field: form_field, variable: variable
+-# EE-specific end
+```
+
+EE-specific comments should not be backported to CE.
+
+**Note:** This is only meant as a workaround, we should follow up and
+resolve this soon.
+
 ### Detection of EE-only files
 
 For each commit (except on `master`), the `ee-files-location-check` CI job tries
@@ -85,11 +108,14 @@ is applied not only to models. Here's a list of other examples:
 - `ee/app/services/foo/create_service.rb`
 - `ee/app/validators/foo_attr_validator.rb`
 - `ee/app/workers/foo_worker.rb`
+- `ee/app/views/foo.html.haml`
+- `ee/app/views/foo/_bar.html.haml`
 
 This works because for every path that are present in CE's eager-load/auto-load
 paths, we add the same `ee/`-prepended path in [`config/application.rb`].
+This also applies to views.
 
-[`config/application.rb`]: https://gitlab.com/gitlab-org/gitlab-ee/blob/d278b76d6600a0e27d8019a0be27971ba23ab640/config/application.rb#L41-51
+[`config/application.rb`]: https://gitlab.com/gitlab-org/gitlab-ee/blob/925d3d4ebc7a2c72964ce97623ae41b8af12538d/config/application.rb#L42-52
 
 ### EE features based on CE features
 
@@ -259,7 +285,7 @@ end
 ```
 
 In `lib/gitlab/visibility_level.rb` this method is used to return the
-allowed visibilty levels:
+allowed visibility levels:
 
 ```ruby
 def levels_for_user(user = nil)
@@ -339,9 +365,63 @@ Blocks of code that are EE-specific should be moved to partials. This
 avoids conflicts with big chunks of HAML code that that are not fun to
 resolve when you add the indentation to the equation.
 
-EE-specific views should be placed in `ee/app/views/ee/`, using extra
+EE-specific views should be placed in `ee/app/views/`, using extra
 sub-directories if appropriate.
 
+#### Using `render_if_exists`
+
+Instead of using regular `render`, we should use `render_if_exists`, which
+will not render anything if it cannot find the specific partial. We use this
+so that we could put `render_if_exists` in CE, keeping code the same between
+CE and EE.
+
+The advantages of this:
+
+- Minimal code difference between CE and EE.
+- Very clear hints about where we're extending EE views while reading CE codes.
+
+The disadvantage of this:
+
+- Slightly more work while developing EE features, because now we need to
+  port `render_if_exists` to CE.
+- If we have typos in the partial name, it would be silently ignored.
+
+#### Using `render_ce`
+
+For `render` and `render_if_exists`, they search for the EE partial first,
+and then CE partial. They would only render a particular partial, not all
+partials with the same name. We could take the advantage of this, so that
+the same partial path (e.g. `shared/issuable/form/default_templates`) could
+be referring to the CE partial in CE (i.e.
+`app/views/shared/issuable/form/_default_templates.html.haml`), while EE
+partial in EE (i.e.
+`ee/app/views/shared/issuable/form/_default_templates.html.haml`). This way,
+we could show different things between CE and EE.
+
+However sometimes we would also want to reuse the CE partial in EE partial
+because we might just want to add something to the existing CE partial. We
+could workaround this by adding another partial with a different name, but it
+would be tedious to do so.
+
+In this case, we could as well just use `render_ce` which would ignore any EE
+partials. One example would be
+`ee/app/views/shared/issuable/form/_default_templates.html.haml`:
+
+``` haml
+- if @project.feature_available?(:issuable_default_templates)
+  = render_ce 'shared/issuable/form/default_templates'
+- elsif show_promotions?
+  = render 'shared/promotions/promote_issue_templates'
+```
+
+In the above example, we can't use
+`render 'shared/issuable/form/default_templates'` because it would find the
+same EE partial, causing infinite recursion. Instead, we could use `render_ce`
+so it ignores any partials in `ee/` and then it would render the CE partial
+(i.e. `app/views/shared/issuable/form/_default_templates.html.haml`)
+for the same path (i.e. `shared/issuable/form/default_templates`). This way
+we could easily wrap around the CE partial.
+
 ### Code in `lib/`
 
 Place EE-specific logic in the top-level `EE` module namespace. Namespace the
@@ -350,6 +430,255 @@ class beneath the `EE` module just as you would normally.
 For example, if CE has LDAP classes in `lib/gitlab/ldap/` then you would place
 EE-specific LDAP classes in `ee/lib/ee/gitlab/ldap`.
 
+### Code in `lib/api/`
+
+It can be very tricky to extend EE features by a single line of `prepend`,
+and for each different [Grape](https://github.com/ruby-grape/grape) feature,
+we might need different strategies to extend it. To apply different strategies
+easily, we would use `extend ActiveSupport::Concern` in the EE module.
+
+Put the EE module files following
+[EE features based on CE features](#ee-features-based-on-ce-features).
+
+#### EE API routes
+
+For EE API routes, we put them in a `prepended` block:
+
+``` ruby
+module EE
+  module API
+    module MergeRequests
+      extend ActiveSupport::Concern
+
+      prepended do
+        params do
+          requires :id, type: String, desc: 'The ID of a project'
+        end
+        resource :projects, requirements: ::API::API::PROJECT_ENDPOINT_REQUIREMENTS do
+          # ...
+        end
+      end
+    end
+  end
+end
+```
+
+Note that due to namespace differences, we need to use the full qualifier for some
+constants.
+
+#### EE params
+
+We can define `params` and utilize `use` in another `params` definition to
+include params defined in EE. However, we need to define the "interface" first
+in CE in order for EE to override it. We don't have to do this in other places
+due to `prepend`, but Grape is complex internally and we couldn't easily do
+that, so we'll follow regular object-oriented practices that we define the
+interface first here.
+
+For example, suppose we have a few more optional params for EE, given this CE
+API code:
+
+``` ruby
+module API
+  class MergeRequests < Grape::API
+    # EE::API::MergeRequests would override the following helpers
+    helpers do
+      params :optional_params_ee do
+      end
+    end
+
+    prepend EE::API::MergeRequests
+
+    params :optional_params do
+      # CE specific params go here...
+
+      use :optional_params_ee
+    end
+  end
+end
+```
+
+And then we could override it in EE module:
+
+``` ruby
+module EE
+  module API
+    module MergeRequests
+      extend ActiveSupport::Concern
+
+      prepended do
+        helpers do
+          params :optional_params_ee do
+            # EE specific params go here...
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+This way, the only difference between CE and EE for that API file would be
+`prepend EE::API::MergeRequests`.
+
+#### EE helpers
+
+To make it easy for an EE module to override the CE helpers, we need to define
+those helpers we want to extend first. Try to do that immediately after the
+class definition to make it easy and clear:
+
+``` ruby
+module API
+  class JobArtifacts < Grape::API
+    # EE::API::JobArtifacts would override the following helpers
+    helpers do
+      def authorize_download_artifacts!
+        authorize_read_builds!
+      end
+    end
+
+    prepend EE::API::JobArtifacts
+  end
+end
+```
+
+And then we can follow regular object-oriented practices to override it:
+
+``` ruby
+module EE
+  module API
+    module JobArtifacts
+      extend ActiveSupport::Concern
+
+      prepended do
+        helpers do
+          def authorize_download_artifacts!
+            super
+            check_cross_project_pipelines_feature!
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+#### EE-specific behaviour
+
+Sometimes we need EE-specific behaviour in some of the APIs. Normally we could
+use EE methods to override CE methods, however API routes are not methods and
+therefore can't be simply overridden. We need to extract them into a standalone
+method, or introduce some "hooks" where we could inject behavior in the CE
+route. Something like this:
+
+``` ruby
+module API
+  class MergeRequests < Grape::API
+    helpers do
+      # EE::API::MergeRequests would override the following helpers
+      def update_merge_request_ee(merge_request)
+      end
+    end
+
+    prepend EE::API::MergeRequests
+
+    put ':id/merge_requests/:merge_request_iid/merge' do
+      merge_request = find_project_merge_request(params[:merge_request_iid])
+
+      # ...
+
+      update_merge_request_ee(merge_request)
+
+      # ...
+    end
+  end
+end
+```
+
+Note that `update_merge_request_ee` doesn't do anything in CE, but
+then we could override it in EE:
+
+``` ruby
+module EE
+  module API
+    module MergeRequests
+      extend ActiveSupport::Concern
+
+      prepended do
+        helpers do
+          def update_merge_request_ee(merge_request)
+            # ...
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+#### EE `route_setting`
+
+It's very hard to extend this in an EE module, and this is simply storing
+some meta-data for a particular route. Given that, we could simply leave the
+EE `route_setting` in CE as it won't hurt and we are just not going to use
+those meta-data in CE.
+
+We could revisit this policy when we're using `route_setting` more and whether
+or not we really need to extend it from EE. For now we're not using it much.
+
+#### Utilizing class methods for setting up EE-specific data
+
+Sometimes we need to use different arguments for a particular API route, and we
+can't easily extend it with an EE module because Grape has different context in
+different blocks. In order to overcome this, we could use class methods from the
+API class.
+
+For example, in one place we need to pass an extra argument to
+`at_least_one_of` so that the API could consider an EE-only argument as the
+least argument. This is not quite beautiful but it's working:
+
+``` ruby
+module API
+  class MergeRequests < Grape::API
+    def self.update_params_at_least_one_of
+      %i[
+        assignee_id
+        description
+      ]
+    end
+
+    prepend EE::API::MergeRequests
+
+    params do
+      at_least_one_of(*::API::MergeRequests.update_params_at_least_one_of)
+    end
+  end
+end
+```
+
+And then we could easily extend that argument in the EE class method:
+
+``` ruby
+module EE
+  module API
+    module MergeRequests
+      extend ActiveSupport::Concern
+
+      class_methods do
+        def update_params_at_least_one_of
+          super.push(*%i[
+            squash
+          ])
+        end
+      end
+    end
+  end
+end
+```
+
+It could be annoying if we need this for a lot of routes, but it might be the
+simplest solution right now.
+
 ### Code in `spec/`
 
 When you're testing EE-only features, avoid adding examples to the
@@ -375,6 +704,7 @@ information on managing page-specific javascript within EE.
 To separate EE-specific styles in SCSS files, if a component you're adding styles for
 is limited to only EE, it is better to have a separate SCSS file in appropriate directory
 within `app/assets/stylesheets`.
+See [backporting changes](#backporting-changes) for instructions on how to merge changes safely.
 
 In some cases, this is not entirely possible or creating dedicated SCSS file is an overkill,
 e.g. a text style of some component is different for EE. In such cases,
@@ -405,14 +735,28 @@ to avoid conflicts during CE to EE merge.
   }
 }
 
-/* EE-specific styles */
+// EE-specific start
 .section-body.ee-section-body {
   .section-title {
     background: $gl-header-color-cyan;
   }
 }
+// EE-specific end
 ```
 
+### Backporting changes from EE to CE
+
+When working in EE-specific features, you might have to tweak a few files that are not EE-specific. Here is a workflow to make sure those changes end up backported safely into CE too.
+(This approach does not refer to changes introduced via [csslab](https://gitlab.com/gitlab-org/csslab/).)
+
+1. **Make your changes in the EE branch.** If possible, keep a separated commit (to be squashed) to help backporting and review.
+1. **Open merge request to EE project.**
+1. **Apply the changes you made to CE files in a branch of the CE project.** (Tip: Use `patch` with the diff from your commit in EE branch)
+1. **Open merge request to CE project**, referring it's a backport of EE changes and link to MR open in EE.
+1. Once EE MR is merged, the MR towards CE can be merged. **But not before**.
+
+**Note:** regarding SCSS, make sure the files living outside `/ee/` don't diverge between CE and EE projects.
+
 ## gitlab-svgs
 
 Conflicts in `app/assets/images/icons.json` or `app/assets/images/icons.svg` can
diff --git a/doc/development/emails.md b/doc/development/emails.md
index 4dbf064fd75..73cac82caf0 100644
--- a/doc/development/emails.md
+++ b/doc/development/emails.md
@@ -74,6 +74,24 @@ See the [Rails guides] for more info.
 
 1. Reply by email should now be working.
 
+## Email namespace
+
+If you need to implement a new feature which requires a new email handler, follow these rules:
+
+ - You must choose a namespace. The namespace cannot contain `/` or `+`, and cannot match `\h{16}`.
+ - If your feature is related to a project, you will append the namespace **after** the project path, separated by a `+`
+ - If you have different actions in the namespace, you add the actions **after** the namespace separated by a `+`. The action name cannot contain `/` or `+`, , and cannot match `\h{16}`.
+ - You will register your handlers in `lib/gitlab/email/handler.rb`
+
+Therefore, these are the only valid formats for an email handler:
+
+ - `path/to/project+namespace`
+ - `path/to/project+namespace+action`
+ - `namespace`
+ - `namespace+action`
+
+Please note that `path/to/project` is used in GitLab Premium as handler for the Service Desk feature.
+
 ---
 
 [Return to Development documentation](README.md)
diff --git a/doc/development/fe_guide/development_process.md b/doc/development/fe_guide/development_process.md
new file mode 100644
index 00000000000..d240dbe8b02
--- /dev/null
+++ b/doc/development/fe_guide/development_process.md
@@ -0,0 +1,77 @@
+# Frontend Development Process
+
+You can find more about the organization of the frontend team in the [handbook](https://about.gitlab.com/handbook/frontend/).
+
+## Development Checklist
+
+The idea is to remind us about specific topics during the time we build a new feature or start something. This is a common practice in other industries (like pilots) that also use  standardised checklists to reduce problems early on.
+
+Copy the content over to your issue or merge request and if something doesn't apply simply remove it from your current list.
+
+This checklist is intended to help us during development of bigger features/refactorings, it's not a "use it always and every point always matches" list.
+
+Please use your best judgement when to use it and please contribute new points through merge requests if something comes to your mind.
+
+---
+
+### Frontend development
+
+#### Planning development
+
+- [ ] Check the current set weight of the issue, does it fit your estimate?
+- [ ] Are all [departments](https://about.gitlab.com/handbook/engineering/#engineering-teams) that are needed from your perspective already involved in the issue? (For example is UX missing?)
+- [ ] Is the specification complete? Are you missing decisions? How about error handling/defaults/edge cases? Take your time to understand the needed implementation and go through its flow.
+- [ ] Are all necessary UX specifications available that you will need in order to implement? Are there new UX components/patterns in the designs? Then contact the UI component team early on. How should error messages or validation be handled?
+- [ ] **Library usage** Use Vuex as soon as you have even a medium state to manage, use Vue router if you need to have different views internally and want to link from the outside. Check what libraries we already have for which occasions.
+- [ ] **Plan your implementation:**
+    - [ ] **Architecture plan:** Create a plan aligned with GitLab's architecture, how you are going to do the implementation, for example Vue application setup and its components (through [onion skinning](https://gitlab.com/gitlab-org/gitlab-ce/issues/35873#note_39994091)), Store structure and data flow, which existing Vue components can you reuse. It's a good idea to go through your plan with another engineer to refine it.
+    - [ ] **Backend:** The best way is to kickoff the implementation in a call and discuss with the assigned Backend engineer what you will need from the backend and also when. Can you reuse existing API's? How is the performance with the planned architecture? Maybe create together a JSON mock object to already start with development.
+    - [ ] **Communication:** It also makes sense to have for bigger features an own slack channel (normally called #f_{feature_name}) and even weekly demo calls with all people involved.
+    - [ ] **Dependency Plan:** Are there big dependencies in the plan between you and others, then maybe create an execution diagram to show what is blocking which part and the order of the different parts.
+    - [ ] **Task list:** Create a simple checklist of the subtasks that are needed for the implementation, also consider creating even sub issues. (for example show a comment, delete a comment, update a comment, etc.). This helps you and also everyone else following the implementation
+- [ ] **Keep it small** To make it easier for you and also all reviewers try to keep merge requests small and merge into a feature branch if needed. To accomplish that you need to plan that from the start. Different methods are:
+    - [ ] **Skeleton based plan** Start with an MR that has the skeleton of the components with placeholder content. In following MRs you can fill the components with interactivity. This also makes it easier to spread out development on multiple people.
+    - [ ] **Cookie Mode** Think about hiding the feature behind a cookie flag if the implementation is on top of existing features
+    - [ ] **New route** Are you refactoring something big then you might consider adding a new route where you implement the new feature and when finished delete the current route and rename the new one. (for example 'merge_request' and 'new_merge_request')
+- [ ] **Setup** Is there any specific setup needed for your implementation (for example a kubernetes cluster)? Then let everyone know if it is not already mentioned where they can find documentation (if it doesn't exist - create it)
+- [ ] **Security** Are there any new security relevant implementations? Then please contact the security team for an app security review. If you are not sure ask our [domain expert](https://about.gitlab.com/handbook/frontend/#frontend-domain-experts)
+
+#### During development
+
+- [ ] Check off tasks on your created task list to keep everyone updated on the progress
+- [ ] [Share your work early with reviewers/maintainers](#share-your-work-early)
+- [ ] Share your work with UXer and Product Manager with Screenshots and/or [GIF's](https://about.gitlab.com/handbook/product/making-gifs/). They are easy to create for you and keep them up to date.
+- [ ] If you are blocked on something let everyone on the issue know through a comment.
+- [ ] Are you unable to work on this issue for a longer period of time, also let everyone know.
+- [ ] **Documentation** Update/add docs for the new feature, see `docs/`. Ping one of the documentation experts/reviewers
+
+#### Finishing development + Review
+
+- [ ] **Keep it in the scope** Try to focus on the actual scope and avoid a scope creep during review and keep new things to new issues.
+- [ ] **Performance** Have you checked performance? For example do the same thing with 500 comments instead of 1. Document the tests and possible findings in the MR so a reviewer can directly see it.
+- [ ] Have you tested with a variety of our [supported browsers](../../install/requirements.md#supported-web-browsers)? You can use [browserstack](https://www.browserstack.com/) to be able to access a wide variety of browsers and operating systems.
+- [ ] Did you check the mobile view?
+- [ ] Check the built webpack bundle (For the report run `WEBPACK_REPORT=true gdk run`, then open `webpack-report/index.html`) if we have unnecessary bloat due to wrong references, including libraries multiple times, etc.. If you need help contact the webpack [domain expert](https://about.gitlab.com/handbook/frontend/#frontend-domain-experts)
+- [ ] **Tests** Not only greenfield tests - Test also all bad cases that come to your mind.
+- [ ] If you have multiple MR's then also smoke test against the final merge.
+- [ ] Are there any big changes on how and especially how frequently we use the API then let production know about it
+- [ ] Smoke test of the RC on dev., staging., canary deployments and .com
+- [ ] Follow up on issues that came out of the review. Create issues for discovered edge cases that should be covered in future iterations.
+
+---
+
+### Share your work early
+1. Before writing code, ensure your vision of the architecture is aligned with
+GitLab's architecture.
+1. Add a diagram to the issue and ask a frontend architect in the slack channel `#fe_architectural` 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.
diff --git a/doc/development/fe_guide/icons.md b/doc/development/fe_guide/icons.md
index b288ee95722..3d8da6accc1 100644
--- a/doc/development/fe_guide/icons.md
+++ b/doc/development/fe_guide/icons.md
@@ -1,26 +1,44 @@
-# Icons
+# Icons and SVG Illustrations
 
-We are using SVG Icons in GitLab with a SVG Sprite, due to this the icons are only loaded once and then referenced through an ID. The sprite SVG is located under `/assets/icons.svg`. Our goal is to replace one by one all inline SVG Icons (as those currently bloat the HTML) and also all Font Awesome usages.
+We manage our own Icon and Illustration library in the [gitlab-svgs][gitlab-svgs] repository.
+This repository is published on [npm][npm] and managed as a dependency via yarn.
+You can browse all available Icons and Illustrations [here][svg-preview].
+To upgrade to a new version run `yarn upgrade @gitlab-org/gitlab-svgs`.
 
-### Usage in HAML/Rails
+## Icons
 
-To use a sprite Icon in HAML or Rails we use a specific helper function :
+We are using SVG Icons in GitLab with a SVG Sprite.
+This means the icons are only loaded once, and are referenced through an ID.
+The sprite SVG is located under `/assets/icons.svg`.
+
+Our goal is to replace one by one all inline SVG Icons (as those currently bloat the HTML) and also all Font Awesome icons.
 
-`sprite_icon(icon_name, size: nil, css_class: '')`
+### Usage in HAML/Rails
 
-**icon_name** Use the icon_name that you can find in the SVG Sprite ([Overview is available here](http://gitlab-org.gitlab.io/gitlab-svgs/)`).
+To use a sprite Icon in HAML or Rails we use a specific helper function :
 
-**size (optional)** Use one of the following sizes : 16,24,32,48,72 (this will be translated into a `s16` class)
+```ruby
+sprite_icon(icon_name, size: nil, css_class: '')
+```
 
-**css_class (optional)** If you want to add additional css classes
+-   **icon_name** Use the icon_name that you can find in the SVG Sprite
+    ([Overview is available here][svg-preview]).
+-   **size (optional)** Use one of the following sizes : 16, 24, 32, 48, 72 (this will be translated into a `s16` class)
+-   **css_class (optional)** If you want to add additional css classes
 
 **Example**
 
-`= sprite_icon('issues', size: 72, css_class: 'icon-danger')`
+```haml
+= sprite_icon('issues', size: 72, css_class: 'icon-danger')
+```
 
 **Output from example above**
 
-`<svg class="s72 icon-danger"><use xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="/assets/icons.svg#issues"></use></svg>`
+```html
+<svg class="s72 icon-danger">
+  <use xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="/assets/icons.svg#issues"></use>
+</svg>
+```
 
 ### Usage in Vue
 
@@ -28,33 +46,71 @@ We have a special Vue component for our sprite icons in `\vue_shared\components\
 
 Sample usage :
 
-`<icon
-    name="retry"
-    :size="32"
-    css-classes="top"
-  />`
-
-**name** Name of the Icon in the SVG Sprite  ([Overview is available here](http://gitlab-org.gitlab.io/gitlab-svgs/)`).
-
-**size (optional)** Number value for the size which is then mapped to a specific CSS class (Available Sizes: 8,12,16,18,24,32,48,72 are mapped to `sXX` css classes)
-
-**css-classes (optional)** Additional CSS Classes to add to the svg tag.
+```javascript
+<script>
+import Icon from "~/vue_shared/components/icon.vue"
+
+export default {
+  components: {
+    Icon,
+  },
+};
+<script>
+<template>
+  <icon
+    name="issues"
+    :size="72"
+    css-classes="icon-danger"
+  />
+</template>
+```
+
+-   **name** Name of the Icon in the SVG Sprite  ([Overview is available here][svg-preview]).
+-   **size (optional)** Number value for the size which is then mapped to a specific CSS class
+    (Available Sizes: 8, 12, 16, 18, 24, 32, 48, 72 are mapped to `sXX` css classes)
+-   **css-classes (optional)** Additional CSS Classes to add to the svg tag.
 
 ### Usage in HTML/JS
 
-Please use the following function inside JS to render an icon :
+Please use the following function inside JS to render an icon:
 `gl.utils.spriteIcon(iconName)`
 
-## Adding a new icon to the sprite
+## SVG Illustrations
 
-All Icons and Illustrations are managed in the [gitlab-svgs](https://gitlab.com/gitlab-org/gitlab-svgs) repository which is added as a dev-dependency.
+Please use from now on for any SVG based illustrations simple `img` tags to show an illustration by simply using either `image_tag` or `image_path` helpers.
+Please use the class `svg-content` around it to ensure nice rendering.
 
-To upgrade to a new SVG Sprite version run `yarn upgrade @gitlab-org/gitlab-svgs` and then run `yarn run svg`. This task will copy the svg sprite and all illustrations in the correct folders. The updated files should be tracked in Git as those are referenced.
+### Usage in HAML/Rails
 
-# SVG Illustrations
+**Example**
 
-Please use from now on for any SVG based illustrations simple `img` tags to show an illustration by simply using either `image_tag` or `image_path` helpers. Please use the class `svg-content` around it to ensure nice rendering. The illustrations are also organised in the [gitlab-svgs](https://gitlab.com/gitlab-org/gitlab-svgs) repository (as they are then automatically optimised).
+```haml
+.svg-content
+  = image_tag 'illustrations/merge_requests.svg'
+```
 
-**Example**
+### Usage in Vue
 
-`= image_tag 'illustrations/merge_requests.svg'`
+To use an SVG illustrations in a template provide the path as a property and display it through a standard img tag.
+
+Component:
+
+```js
+<script>
+export default {
+  props: {
+    svgIllustrationPath: {
+      type: String,
+      required: true,
+    },
+  },
+};
+<script>
+<template>
+  <img :src="svgIllustrationPath" />
+</template>
+```
+
+[npm]: https://www.npmjs.com/package/@gitlab-org/gitlab-svgs
+[gitlab-svgs]: https://gitlab.com/gitlab-org/gitlab-svgs
+[svg-preview]: https://gitlab-org.gitlab.io/gitlab-svgs
diff --git a/doc/development/fe_guide/index.md b/doc/development/fe_guide/index.md
index 2280cf79f86..11b9a2e6a64 100644
--- a/doc/development/fe_guide/index.md
+++ b/doc/development/fe_guide/index.md
@@ -1,15 +1,22 @@
 # Frontend Development Guidelines
 
+> **Notice:**
+We are currently in the process of re-writing our development guide to make it easier to find information. The new guide is still WIP but viewable in [development/new_fe_guide](../new_fe_guide/index.md)
+
 This document describes various guidelines to ensure consistency and quality
 across GitLab's frontend team.
 
 ## Overview
 
-GitLab is built on top of [Ruby on Rails][rails] using [Haml][haml] with
-[Hamlit][hamlit]. Be wary of [the limitations that come with using
-Hamlit][hamlit-limits]. We also use [SCSS][scss] and plain JavaScript with
-modern ECMAScript standards supported through [Babel][babel] and ES module
-support through [webpack][webpack].
+GitLab is built on top of [Ruby on Rails][rails] using [Haml][haml] and also a JavaScript based Frontend with [Vue.js][vue].
+Be wary of [the limitations that come with using Hamlit][hamlit-limits]. We also use [SCSS][scss] and plain JavaScript with
+modern ECMAScript standards supported through [Babel][babel] and ES module support through [webpack][webpack].
+
+### Javascript development
+
+[Vue.js][vue] is used for particularly advanced, dynamic elements and based on previous iterations [jQuery][jquery] is used in lot of places through the application's JavaScript.
+
+We also use [Axios][axios] to handle all of our network requests.
 
 We also utilize [webpack][webpack] to handle the bundling, minification, and
 compression of our assets.
@@ -18,66 +25,37 @@ Working with our frontend assets requires Node (v6.0 or greater) and Yarn
 (v1.2 or greater).  You can find information on how to install these on our
 [installation guide][install].
 
-[jQuery][jquery] is used throughout the application's JavaScript, with
-[Vue.js][vue] for particularly advanced, dynamic elements.
-
-We also use [Axios][axios] to handle all of our network requests.
-
 ### Browser Support
 
 For our currently-supported browsers, see our [requirements][requirements].
 
 ---
 
-## Development Process
-
-### 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.
-
-
----
+## [Development Process](development_process.md)
+How we plan and execute the work on the frontend.
 
 ## [Architecture](architecture.md)
 How we go about making fundamental design decisions in GitLab's frontend team
 or make changes to our frontend development guidelines.
 
----
-
 ## [Testing](../testing_guide/frontend_testing.md)
-
 How we write frontend tests, run the GitLab test suite, and debug test related
 issues.
 
----
-
 ## [Design Patterns](design_patterns.md)
 Common JavaScript design patterns in GitLab's codebase.
 
----
-
 ## [Vue.js Best Practices](vue.md)
 Vue specific design patterns and practices.
 
----
+## [Vuex](vuex.md)
+Vuex specific design patterns and practices.
 
 ## [Axios](axios.md)
 Axios specific practices and gotchas.
 
-## [Icons](icons.md)
-How we use SVG for our Icons.
+## [Icons and Illustrations](icons.md)
+How we use SVG for our Icons and Illustrations.
 
 ## [Components](components.md)
 
diff --git a/doc/development/fe_guide/style_guide_js.md b/doc/development/fe_guide/style_guide_js.md
index 7b5fa6ca42f..284b4b53334 100644
--- a/doc/development/fe_guide/style_guide_js.md
+++ b/doc/development/fe_guide/style_guide_js.md
@@ -236,7 +236,7 @@ export class Foo {
 }
 ```
 
-On the other hand, if a class only needs to extend a third party/add event listeners in some specific cases, they should be initialized oustside of the constructor.
+On the other hand, if a class only needs to extend a third party/add event listeners in some specific cases, they should be initialized outside of the constructor.
 
 1. Prefer `.map`, `.reduce` or `.filter` over `.forEach`
 A forEach will most likely cause side effects, it will be mutating the array being iterated. Prefer using `.map`,
@@ -310,7 +310,7 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation.
     }));
   ```
 
-1. Don not use a singleton for the service or the store
+1. Do not use a singleton for the service or the store
   ```javascript
     // bad
     class Store {
@@ -328,9 +328,11 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation.
       }
     }
   ```
+1. Use `.vue` for Vue templates. Do not use `%template` in HAML.
 
 #### Naming
-1. **Extensions**: Use `.vue` extension for Vue components.
+
+1. **Extensions**: Use `.vue` extension for Vue components. Do not use `.js` as file extension ([#34371]).
 1. **Reference Naming**: Use PascalCase for their instances:
   ```javascript
     // bad
@@ -364,6 +366,8 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation.
     <component my-prop="prop" />
   ```
 
+[#34371]: https://gitlab.com/gitlab-org/gitlab-ce/issues/34371
+
 #### Alignment
 1. Follow these alignment styles for the template method:
   1. With more than one attribute, all attributes should be on a new line:
@@ -628,7 +632,7 @@ Useful links:
     // good
     <span title="tooltip text">Foo</span>
 
-    $('span').tooltip('fixTitle');
+    $('span').tooltip('_fixTitle');
   ```
 
 ### The Javascript/Vue Accord
diff --git a/doc/development/fe_guide/style_guide_scss.md b/doc/development/fe_guide/style_guide_scss.md
index 655d94793dd..48eb6d0a7d6 100644
--- a/doc/development/fe_guide/style_guide_scss.md
+++ b/doc/development/fe_guide/style_guide_scss.md
@@ -216,12 +216,12 @@ If you want a line or set of lines to be ignored by the linter, you can use
 `// scss-lint:disable RuleName` ([more info][disabling-linters]):
 
 ```scss
-// This lint rule is disabled because the class name comes from a gem.
-// scss-lint:disable SelectorFormat
-.ui_indigo {
-  background-color: #333;
+// This lint rule is disabled because it is supported only in Chrome/Safari
+// scss-lint:disable PropertySpelling
+body {
+  text-decoration-skip: ink;
 }
-// scss-lint:enable SelectorFormat
+// scss-lint:enable PropertySpelling
 ```
 
 Make sure a comment is added on the line above the `disable` rule, otherwise the
diff --git a/doc/development/fe_guide/vue.md b/doc/development/fe_guide/vue.md
index c1170fa3b13..e31ee087358 100644
--- a/doc/development/fe_guide/vue.md
+++ b/doc/development/fe_guide/vue.md
@@ -1,36 +1,14 @@
 # Vue
 
-For more complex frontend features, we recommend using Vue.js. It shares
-some ideas with React.js as well as Angular.
-
 To get started with Vue, read through [their documentation][vue-docs].
 
-## When to use Vue.js
-
-We recommend using Vue for more complex features. Here are some guidelines for when to use Vue.js:
-
-- If you are starting a new feature or refactoring an old one that highly interacts with the DOM;
-- For real time data updates;
-- If you are creating a component that will be reused elsewhere;
-
-## When not to use Vue.js
-
-We don't want to refactor all GitLab frontend code into Vue.js, here are some guidelines for
-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 without reactive data;
-
-As always, the Frontend Architectural Experts are available to help with any Vue or JavaScript questions.
-
 ## Vue architecture
 
 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, you can either use [vuex](#vuex) or use the [store pattern][state-management], explained below:
 
-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.
+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.
@@ -39,7 +17,7 @@ This component is responsible for:
 1. Calling the Store to store the data received
 1. Mounting all the other components
 
-  ![Vue Architecture](img/vue_arch.png)
+![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].
@@ -57,15 +35,15 @@ new_feature
 │   └── ...
 ├── stores
 │  └── new_feature_store.js
-├── services
+├── services # only when not using vuex
 │  └── new_feature_service.js
-├── new_feature_bundle.js
+├── index.js
 ```
 _For consistency purposes, we recommend you to follow the same structure._
 
 Let's look into each of them:
 
-### A `*_bundle.js` file
+### A `index.js` file
 
 This is the index file of your new feature. This is where the root Vue instance
 of the new feature should be.
@@ -73,14 +51,14 @@ 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.
 
-Don't forget to follow [these steps.][page_specific_javascript]
+Don't forget to follow [these steps][page_specific_javascript].
 
 ### Bootstrapping Gotchas
-#### Providing data from Haml to JavaScript
+#### Providing data from HAML to JavaScript
 While mounting a Vue application may be a need to provide data from Rails to JavaScript.
 To do that, provide the data through `data` attributes in the HTML element and query them while mounting the application.
 
-_Note:_ You should only do this while initing the application, because the mounted element will be replaced with Vue-generated DOM.
+_Note:_ You should only do this while initializing the application, because the mounted element will be replaced with Vue-generated DOM.
 
 The advantage of providing data from the DOM to the Vue instance through `props` in the `render` function
 instead of querying the DOM inside the main vue component is that makes tests easier by avoiding the need to
@@ -90,6 +68,7 @@ create a fixture or an HTML element in the unit test. See the following example:
 // haml
 .js-vue-app{ data: { endpoint: 'foo' }}
 
+// index.js
 document.addEventListener('DOMContentLoaded', () => new Vue({
   el: '.js-vue-app',
   data() {
@@ -109,13 +88,11 @@ document.addEventListener('DOMContentLoaded', () => new Vue({
 ```
 
 #### Accessing the `gl` object
-When we need to query the `gl` object for data that won't change during the application's lyfecyle, we should do it in the same place where we query the DOM.
+When we need to query the `gl` object for data that won't change during the application's life cyle, we should do it in the same place where we query the DOM.
 By following this practice, we can avoid the need to mock the `gl` object, which will make tests easier.
 It should be done while initializing our Vue instance, and the data should be provided as `props` to the main component:
 
-##### example:
 ```javascript
-
 document.addEventListener('DOMContentLoaded', () => new Vue({
   el: '.js-vue-app',
   render(createElement) {
@@ -143,31 +120,12 @@ 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]
 
-#### Components Gotchas
-1. Using SVGs in components: To use an SVG in a template we need to make it a property we can access through the component.
-A `prop` and a property returned by the `data` functions require `vue` to set a `getter` and a `setter` for each of them.
-The SVG should be a computed property in order to improve performance, note that computed properties are cached based on their dependencies.
-
-```javascript
-// bad
-import svg from 'svg.svg';
-data() {
-  return {
-    myIcon: svg,
-  };
-};
-
-// good
-import svg from 'svg.svg';
-computed: {
-  myIcon() {
-    return svg;
-  }
-}
-```
-
 ### A folder for the Store
 
+#### Vuex
+Check this [page](vuex.md) for more details.
+
+#### Flux like state management
 The Store is a class that allows us to manage the state in a single
 source of truth. It is not aware of the service or the components.
 
@@ -176,6 +134,8 @@ itself, please read this guide: [State Management][state-management]
 
 ### A folder for the Service
 
+**If you are using Vuex you won't need this step**
+
 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 [axios][axios] to communicate with the server.
@@ -183,13 +143,13 @@ Refer to [axios](axios.md) for more details.
 
 Axios instance should only be imported in the service file.
 
-  ```javascript
-  import axios from 'javascripts/lib/utils/axios_utils';
-  ```
+```javascript
+import axios from '~/lib/utils/axios_utils';
+```
 
 ### End Result
 
-The following example shows an  application:
+The following example shows an application:
 
 ```javascript
 // store.js
@@ -197,8 +157,8 @@ 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.
+   * Usually in a small SPA you don't need any options when starting the store.
+   * In that case you do need guarantee it's an Object and it's documented.
    *
    * @param  {Object} options
    */
@@ -206,7 +166,7 @@ export default class Store {
     this.options = options;
 
     // Create a state object to handle all our data in the same place
-    this.todos = []:
+    this.todos = [];
   }
 
   setTodos(todos = []) {
@@ -227,7 +187,7 @@ export default class Store {
 }
 
 // service.js
-import axios from 'javascripts/lib/utils/axios_utils'
+import axios from '~/lib/utils/axios_utils'
 
 export default class Service {
   constructor(options) {
@@ -253,8 +213,8 @@ export default {
       type: Object,
       required: true,
     },
-  }
-}
+  },
+};
 </script>
 <template>
   <div>
@@ -273,6 +233,9 @@ import Store from 'store';
 import Service from 'service';
 import TodoComponent from 'todoComponent';
 export default {
+  components: {
+    todo: TodoComponent,
+  },
   /**
    * 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
@@ -291,12 +254,8 @@ export default {
     };
   },
 
-  components: {
-    todo: TodoComponent,
-  },
-
   created() {
-    this.service = new Service('todos');
+    this.service = new Service('/todos');
 
     this.getTodos();
   },
@@ -305,9 +264,9 @@ export default {
     getTodos() {
       this.isLoading = true;
 
-      this.service.getTodos()
-        .then(response => response.json())
-        .then((response) => {
+      this.service
+        .getTodos()
+        .then(response => {
           this.store.setTodos(response);
           this.isLoading = false;
         })
@@ -317,18 +276,21 @@ export default {
         });
     },
 
-    addTodo(todo) {
-      this.service.addTodo(todo)
-      then(response => response.json())
-      .then((response) => {
-        this.store.addTodo(response);
-      })
-      .catch(() => {
-        // Show an error
-      });
-    }
-  }
-}
+    addTodo(event) {
+      this.service
+        .addTodo({
+          title: 'New entry',
+          text: `You clicked on ${event.target.tagName}`,
+        })
+        .then(response => {
+          this.store.addTodo(response);
+        })
+        .catch(() => {
+          // Show an error
+        });
+    },
+  },
+};
 </script>
 <template>
   <div class="container">
@@ -354,7 +316,7 @@ export default {
   <div>
 </template>
 
-// bundle.js
+// index.js
 import todoComponent from 'todos_main_component.vue';
 
 new Vue({
@@ -386,76 +348,79 @@ Each Vue component has a unique output. This output is always present in the ren
 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.
+Make use of the [axios mock adapter](axios.md#mock-axios-response-on-tests) to mock data returned.
 
 Here's how we would test the Todo App above:
 
 ```javascript
-import component from 'todos_main_component';
+import Vue from 'vue';
+import axios from '~/lib/utils/axios_utils';
+import MockAdapter from 'axios-mock-adapter';
 
 describe('Todos App', () => {
-  it('should render the loading state while the request is being made', () => {
+  let vm;
+  let mock;
+
+  beforeEach(() => {
+    // Create a mock adapter for stubbing axios API requests
+    mock = new MockAdapter(axios);
+
     const Component = Vue.extend(component);
 
-    const vm = new Component().$mount();
+    // Mount the Component
+    vm = new Component().$mount();
+  });
 
+  afterEach(() => {
+    // Reset the mock adapter
+    mock.restore();
+    // Destroy the mounted component
+    vm.$destroy();
+  });
+
+  it('should render the loading state while the request is being made', () => {
     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([{
+  it('should render todos returned by the endpoint', done => {
+    // Mock the get request on the API endpoint to return data
+    mock.onGet('/todos').replyOnce(200, [
+      {
         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);
+        text: 'This is the text',
+      },
+    ]);
 
-      vm = new Component().$mount();
+    Vue.nextTick(() => {
+      const items = vm.$el.querySelectorAll('.js-todo-list div')
+      expect(items.length).toBe(1);
+      expect(items[0].textContent).toContain('This is the text');
+      done();
     });
+  });
 
-    afterEach(() => {
-      Vue.http.interceptors = _.without(Vue.http.interceptors, interceptor);
-    });
+  it('should add a todos on button click', (done) => {
 
+    // Mock the put request and check that the sent data object is correct
+    mock.onPut('/todos').replyOnce((req) => {
+      expect(req.data).toContain('text');
+      expect(req.data).toContain('title');
 
-    it('should render todos', (done) => {
-      setTimeout(() => {
-        expect(vm.$el.querySelectorAll('.js-todo-list div').length).toBe(1);
-        done();
-      }, 0);
+      return [201, {}];
     });
-  });
 
-  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();
+    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);
+    // Add a new interceptor to mock the add Todo request
+    Vue.nextTick(() => {
+      expect(vm.$el.querySelectorAll('.js-todo-list div').length).toBe(2);
+      done();
     });
   });
 });
 ```
-#### `mountComponent` helper
+
+### `mountComponent` helper
 There is a helper in `spec/javascripts/helpers/vue_mount_component_helper.js` that allows you to mount a component with the given props:
 
 ```javascript
@@ -468,208 +433,10 @@ const data = {prop: 'foo'};
 const vm = mountComponent(Component, data);
 ```
 
-#### Test the component's output
+### 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
-Refer to [mock axios](axios.md#mock-axios-response-on-tests)
-
-
-## Vuex
-To manage the state of an application you may use [Vuex][vuex-docs].
-
-_Note:_ All of the below is explained in more detail in the official [Vuex documentation][vuex-docs].
-
-### Separation of concerns
-Vuex is composed of State, Getters, Mutations, Actions and Modules.
-
-When a user clicks on an action, we need to `dispatch` it. This action will `commit` a mutation that will change the state.
-_Note:_ The action itself will not update the state, only a mutation should update the state.
-
-#### File structure
-When using Vuex at GitLab, separate this concerns into different files to improve readability. If you can, separate the Mutation Types as well:
-
-```
-└── store
-  ├── index.js          # where we assemble modules and export the store
-  ├── actions.js        # actions
-  ├── mutations.js      # mutations
-  ├── getters.js        # getters
-  └── mutation_types.js # mutation types
-```
-The following examples show an application that lists and adds users to the state.
-
-##### `index.js`
-This is the entry point for our store. You can use the following as a guide:
-
-```javascript
-import Vue from 'vue';
-import Vuex from 'vuex';
-import * as actions from './actions';
-import * as getters from './getters';
-import mutations from './mutations';
-
-Vue.use(Vuex);
-
-export default new Vuex.Store({
-  actions,
-  getters,
-  mutations,
-  state: {
-    users: [],
-  },
-});
-```
-_Note:_ If the state of the application is too complex, an individual file for the state may be better.
-
-#### `actions.js`
-An action commits a mutatation. In this file, we will write the actions that will call the respective mutation:
-
-```javascript
-  import * as types from './mutation_types';
-
-  export const addUser = ({ commit }, user) => {
-    commit(types.ADD_USER, user);
-  };
-```
-
-To dispatch an action from a component, use the `mapActions` helper:
-```javascript
-import { mapActions } from 'vuex';
-
-{
-  methods: {
-    ...mapActions([
-      'addUser',
-    ]),
-    onClickUser(user) {
-      this.addUser(user);
-    },
-  },
-};
-```
-
-#### `getters.js`
-Sometimes we may need to get derived state based on store state, like filtering for a specific prop. This can be done through the `getters`:
-
-```javascript
-// get all the users with pets
-export getUsersWithPets = (state, getters) => {
-  return state.users.filter(user => user.pet !== undefined);
-};
-```
-
-To access a getter from a component, use the `mapGetters` helper:
-```javascript
-import { mapGetters } from 'vuex';
-
-{
-  computed: {
-    ...mapGetters([
-      'getUsersWithPets',
-    ]),
-  },
-};
-```
-
-#### `mutations.js`
-The only way to actually change state in a Vuex store is by committing a mutation.
-
-```javascript
-  import * as types from './mutation_types';
-
-  export default {
-    [types.ADD_USER](state, user) {
-      state.users.push(user);
-    },
-  };
-```
-
-#### `mutations_types.js`
-From [vuex mutations docs][vuex-mutations]:
-> It is a commonly seen pattern to use constants for mutation types in various Flux implementations. This allows the code to take advantage of tooling like linters, and putting all constants in a single file allows your collaborators to get an at-a-glance view of what mutations are possible in the entire application.
-
-```javascript
-export const ADD_USER = 'ADD_USER';
-```
-
-### How to include the store in your application
-The store should be included in the main component of your application:
-```javascript
-  // app.vue
-  import store from 'store'; // it will include the index.js file
-
-  export default {
-    name: 'application',
-    store,
-    ...
-  };
-```
-
-### Vuex Gotchas
-1. Avoid calling a mutation directly. Always use an action to commit a mutation. Doing so will keep consistency through out the application. From Vuex docs:
-
-  >  why don't we just call store.commit('action') directly? Well, remember that mutations must be synchronous? Actions aren't. We can perform asynchronous operations inside an action.
-
-  ```javascript
-    // component.vue
-
-    // bad
-    created() {
-      this.$store.commit('mutation');
-    }
-
-    // good
-    created() {
-      this.$store.dispatch('action');
-    }
-  ```
-1. When possible, use mutation types instead of hardcoding strings. It will be less error prone.
-1. The State will be accessible in all components descending from the use where the store is instantiated.
-
-### Testing Vuex
-#### Testing Vuex concerns
-Refer to [vuex docs][vuex-testing] regarding testing Actions, Getters and Mutations.
-
-#### Testing components that need a store
-Smaller components might use `store` properties to access the data.
-In order to write unit tests for those components, we need to include the store and provide the correct state:
-
-```javascript
-//component_spec.js
-import Vue from 'vue';
-import store from './store';
-import component from './component.vue'
-
-describe('component', () => {
-  let vm;
-  let Component;
-
-  beforeEach(() => {
-    Component = Vue.extend(issueActions);
-  });
-
-  afterEach(() => {
-    vm.$destroy();
-  });
-
-  it('should show a user', () => {
-    const user = {
-      name: 'Foo',
-      age: '30',
-    };
-
-    // populate the store
-    store.dipatch('addUser', user);
-
-    vm = new Component({
-      store,
-      propsData: props,
-    }).$mount();
-  });
-});
-```
 
 [vue-docs]: http://vuejs.org/guide/index.html
 [issue-boards]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/app/assets/javascripts/boards
@@ -681,9 +448,4 @@ describe('component', () => {
 [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
-[vuex-docs]: https://vuex.vuejs.org
-[vuex-structure]: https://vuex.vuejs.org/en/structure.html
-[vuex-mutations]: https://vuex.vuejs.org/en/mutations.html
-[vuex-testing]: https://vuex.vuejs.org/en/testing.html
 [axios]: https://github.com/axios/axios
-[axios-interceptors]: https://github.com/axios/axios#interceptors
diff --git a/doc/development/fe_guide/vuex.md b/doc/development/fe_guide/vuex.md
new file mode 100644
index 00000000000..4089cd37d73
--- /dev/null
+++ b/doc/development/fe_guide/vuex.md
@@ -0,0 +1,374 @@
+# Vuex
+To manage the state of an application you should use [Vuex][vuex-docs].
+
+_Note:_ All of the below is explained in more detail in the official [Vuex documentation][vuex-docs].
+
+## Separation of concerns
+Vuex is composed of State, Getters, Mutations, Actions and Modules.
+
+When a user clicks on an action, we need to `dispatch` it. This action will `commit` a mutation that will change the state.
+_Note:_ The action itself will not update the state, only a mutation should update the state.
+
+## File structure
+When using Vuex at GitLab, separate this concerns into different files to improve readability:
+
+```
+└── store
+  ├── index.js          # where we assemble modules and export the store
+  ├── actions.js        # actions
+  ├── mutations.js      # mutations
+  ├── getters.js        # getters
+  ├── state.js          # state
+  └── mutation_types.js # mutation types
+```
+The following example shows an application that lists and adds users to the state.
+(For a more complex example implementation take a look at the security applications store in [here](https://gitlab.com/gitlab-org/gitlab-ee/tree/master/ee/app/assets/javascripts/vue_shared/security_reports/store))
+
+### `index.js`
+This is the entry point for our store. You can use the following as a guide:
+
+```javascript
+import Vue from 'vue';
+import Vuex from 'vuex';
+import * as actions from './actions';
+import * as getters from './getters';
+import mutations from './mutations';
+import state from './state';
+
+Vue.use(Vuex);
+
+export const createStore = () => new Vuex.Store({
+  actions,
+  getters,
+  mutations,
+  state,
+});
+export default createStore();
+```
+
+### `state.js`
+The first thing you should do before writing any code is to design the state.
+
+Often we need to provide data from haml to our Vue application. Let's store it in the state for better access.
+
+```javascript
+  export default {
+    endpoint: null,
+
+    isLoading: false,
+    error: null,
+
+    isAddingUser: false,
+    errorAddingUser: false,
+
+    users: [],
+  };
+```
+
+#### Access `state` properties
+You can use `mapState` to access state properties in the components.
+
+### `actions.js`
+An action is a payload of information to send data from our application to our store.
+
+An action is usually composed by a `type` and a `payload` and they describe what happened.
+Enforcing that every change is described as an action lets us have a clear understanding of what is going on in the app.
+
+In this file, we will write the actions that will call the respective mutations:
+
+```javascript
+  import * as types from './mutation_types';
+  import axios from '~/lib/utils/axios_utils';
+  import createFlash from '~/flash';
+
+  export const requestUsers = ({ commit }) => commit(types.REQUEST_USERS);
+  export const receiveUsersSuccess = ({ commit }, data) => commit(types.RECEIVE_USERS_SUCCESS, data);
+  export const receiveUsersError = ({ commit }, error) => commit(types.REQUEST_USERS_ERROR, error);
+
+  export const fetchUsers = ({ state, dispatch }) => {
+    dispatch('requestUsers');
+
+    axios.get(state.endpoint)
+      .then(({ data }) => dispatch('receiveUsersSuccess', data))
+      .catch((error) => {
+        dispatch('receiveUsersError', error)
+        createFlash('There was an error')
+      });
+  }
+
+  export const requestAddUser = ({ commit }) => commit(types.REQUEST_ADD_USER);
+  export const receiveAddUserSuccess = ({ commit }, data) => commit(types.RECEIVE_ADD_USER_SUCCESS, data);
+  export const receiveAddUserError = ({ commit }, error) => commit(types.REQUEST_ADD_USER_ERROR, error);
+
+  export const addUser = ({ state, dispatch }, user) => {
+    dispatch('requestAddUser');
+
+    axios.post(state.endpoint, user)
+      .then(({ data }) => dispatch('receiveAddUserSuccess', data))
+      .catch((error) => dispatch('receiveAddUserError', error));
+  }
+```
+
+#### Actions Pattern: `request` and `receive` namespaces
+When a request is made we often want to show a loading state to the user.
+
+Instead of creating an action to toggle the loading state and dispatch it in the component,
+create:
+1. An action `requestSomething`, to toggle the loading state
+1. An action `receiveSomethingSuccess`, to handle the success callback
+1. An action `receiveSomethingError`, to handle the error callback
+1. An action `fetchSomething` to make the request.
+    1. In case your application does more than a `GET` request you can use these as examples:
+        1. `PUT`: `createSomething`
+        2. `POST`: `updateSomething`
+        3. `DELETE`: `deleteSomething`
+
+The component MUST only dispatch the `fetchNamespace` action. Actions namespaced with `request` or `receive` should not be called from the component
+The `fetch` action will be responsible to dispatch `requestNamespace`, `receiveNamespaceSuccess` and `receiveNamespaceError`
+
+By following this pattern we guarantee:
+1. All applications follow the same pattern, making it easier for anyone to maintain the code
+1. All data in the application follows the same lifecycle pattern
+1. Actions are contained and human friendly
+1. Unit tests are easier
+1. Actions are simple and straightforward
+
+#### Dispatching actions
+To dispatch an action from a component, use the `mapActions` helper:
+```javascript
+import { mapActions } from 'vuex';
+
+{
+  methods: {
+    ...mapActions([
+      'addUser',
+    ]),
+    onClickUser(user) {
+      this.addUser(user);
+    },
+  },
+};
+```
+
+### `mutations.js`
+The mutations specify how the application state changes in response to actions sent to the store.
+The only way to change state in a Vuex store should be by committing a mutation.
+
+**It's a good idea to think of the state before writing any code.**
+
+Remember that actions only describe that something happened, they don't describe how the application state changes.
+
+**Never commit a mutation directly from a component**
+
+```javascript
+  import * as types from './mutation_types';
+
+  export default {
+    [types.REQUEST_USERS](state) {
+      state.isLoading = true;
+    },
+    [types.RECEIVE_USERS_SUCCESS](state, data) {
+      // Do any needed data transformation to the received payload here
+      state.users = data;
+      state.isLoading = false;
+    },
+    [types.REQUEST_USERS_ERROR](state, error) {
+      state.isLoading = false;
+    },
+    [types.REQUEST_ADD_USER](state, user) {
+      state.isAddingUser = true;
+    },
+    [types.RECEIVE_ADD_USER_SUCCESS](state, user) {
+      state.isAddingUser = false;
+      state.users.push(user);
+    },
+    [types.REQUEST_ADD_USER_ERROR](state, error) {
+      state.isAddingUser = true;
+      state.errorAddingUser = error;
+    },
+  };
+```
+
+### `getters.js`
+Sometimes we may need to get derived state based on store state, like filtering for a specific prop.
+Using a getter will also cache the result based on dependencies due to [how computed props work](https://vuejs.org/v2/guide/computed.html#Computed-Caching-vs-Methods)
+This can be done through the `getters`:
+
+```javascript
+// get all the users with pets
+export const getUsersWithPets = (state, getters) => {
+  return state.users.filter(user => user.pet !== undefined);
+};
+```
+
+To access a getter from a component, use the `mapGetters` helper:
+```javascript
+import { mapGetters } from 'vuex';
+
+{
+  computed: {
+    ...mapGetters([
+      'getUsersWithPets',
+    ]),
+  },
+};
+```
+
+### `mutation_types.js`
+From [vuex mutations docs][vuex-mutations]:
+> It is a commonly seen pattern to use constants for mutation types in various Flux implementations. This allows the code to take advantage of tooling like linters, and putting all constants in a single file allows your collaborators to get an at-a-glance view of what mutations are possible in the entire application.
+
+```javascript
+export const ADD_USER = 'ADD_USER';
+```
+
+### How to include the store in your application
+The store should be included in the main component of your application:
+```javascript
+  // app.vue
+  import store from 'store'; // it will include the index.js file
+
+  export default {
+    name: 'application',
+    store,
+    ...
+  };
+```
+
+### Communicating with the Store
+```javascript
+<script>
+import { mapActions, mapState, mapGetters } from 'vuex';
+import store from './store';
+
+export default {
+  store,
+  computed: {
+    ...mapGetters([
+      'getUsersWithPets'
+    ]),
+    ...mapState([
+      'isLoading',
+      'users',
+      'error',
+    ]),
+  },
+  methods: {
+    ...mapActions([
+      'fetchUsers',
+      'addUser',
+    ]),
+
+    onClickAddUser(data) {
+      this.addUser(data);
+    }
+  },
+
+  created() {
+    this.fetchUsers()
+  }
+}
+</script>
+<template>
+  <ul>
+    <li v-if="isLoading">
+      Loading...
+    </li>
+    <li v-else-if="error">
+      {{ error }}
+    </li>
+    <template v-else>
+      <li
+        v-for="user in users"
+        :key="user.id"
+      >
+        {{ user }}
+      </li>
+    </template>
+  </ul>
+</template>
+```
+
+### Vuex Gotchas
+1. Do not call a mutation directly. Always use an action to commit a mutation. Doing so will keep consistency throughout the application. From Vuex docs:
+
+  >  why don't we just call store.commit('action') directly? Well, remember that mutations must be synchronous? Actions aren't. We can perform asynchronous operations inside an action.
+
+  ```javascript
+    // component.vue
+
+    // bad
+    created() {
+      this.$store.commit('mutation');
+    }
+
+    // good
+    created() {
+      this.$store.dispatch('action');
+    }
+  ```
+1. Use mutation types instead of hardcoding strings. It will be less error prone.
+1. The State will be accessible in all components descending from the use where the store is instantiated.
+
+### Testing Vuex
+#### Testing Vuex concerns
+Refer to [vuex docs][vuex-testing] regarding testing Actions, Getters and Mutations.
+
+#### Testing components that need a store
+Smaller components might use `store` properties to access the data.
+In order to write unit tests for those components, we need to include the store and provide the correct state:
+
+```javascript
+//component_spec.js
+import Vue from 'vue';
+import { createStore } from './store';
+import component from './component.vue'
+
+describe('component', () => {
+  let store;
+  let vm;
+  let Component;
+
+  beforeEach(() => {
+    Component = Vue.extend(issueActions);
+  });
+
+  afterEach(() => {
+    vm.$destroy();
+  });
+
+  it('should show a user', () => {
+    const user = {
+      name: 'Foo',
+      age: '30',
+    };
+    
+    store = createStore();
+
+    // populate the store
+    store.dispatch('addUser', user);
+
+    vm = new Component({
+      store,
+      propsData: props,
+    }).$mount();
+  });
+});
+```
+
+#### Testing Vuex actions and getters
+Because we're currently using [`babel-plugin-rewire`](https://github.com/speedskater/babel-plugin-rewire), you may encounter the following error when testing your Vuex actions and getters:
+`[vuex] actions should be function or object with "handler" function`
+
+To prevent this error from happening, you need to export an empty function as `default`:
+```
+// getters.js or actions.js
+
+// prevent babel-plugin-rewire from generating an invalid default during karma tests
+export default () => {};
+```
+
+[vuex-docs]: https://vuex.vuejs.org
+[vuex-structure]: https://vuex.vuejs.org/en/structure.html
+[vuex-mutations]: https://vuex.vuejs.org/en/mutations.html
+[vuex-testing]: https://vuex.vuejs.org/en/testing.html
diff --git a/doc/development/file_storage.md b/doc/development/file_storage.md
index 34a02bd2c3c..fdbd7f1fa37 100644
--- a/doc/development/file_storage.md
+++ b/doc/development/file_storage.md
@@ -84,7 +84,7 @@ The `RecordsUploads::Concern` concern will create an `Upload` entry for every fi
 By including the `ObjectStorage::Concern` in the `GitlabUploader` derived class, you may enable the object storage for this uploader. To enable the object storage
 in your uploader, you need to either 1) include `RecordsUpload::Concern` and prepend `ObjectStorage::Extension::RecordsUploads` or 2) mount the uploader and create a new field named `<mount>_store`.
 
-The `CarrierWave::Uploader#store_dir` is overriden to
+The `CarrierWave::Uploader#store_dir` is overridden to
 
  - `GitlabUploader.base_dir` + `GitlabUploader.dynamic_segment` when the store is LOCAL
  - `GitlabUploader.dynamic_segment` when the store is REMOTE (the bucket name is used to namespace)
diff --git a/doc/development/gitaly.md b/doc/development/gitaly.md
index 26abf967dcf..4f9ca1920a5 100644
--- a/doc/development/gitaly.md
+++ b/doc/development/gitaly.md
@@ -7,6 +7,67 @@ be replaced by Gitaly API calls.
 Visit the [Gitaly Migration Board](https://gitlab.com/gitlab-org/gitaly/boards/331341) for current
 status of the migration.
 
+## Developing new Git features
+
+Starting with Gitlab 10.8, all new Git features should be developed in
+Gitaly.
+
+> This is a new process that is not clearly defined yet. If you want
+to contribute a Git feature and you're getting stuck, reach out to the
+Gitaly team or `@jacobvosmaer-gitlab`.
+
+By 'new feature' we mean any method or class in `lib/gitlab/git` that is
+called from outside `lib/gitlab/git`. For new methods that are called
+from inside `lib/gitlab/git`, see 'Modifying existing Git features'
+below.
+
+There should be no new code that touches Git repositories via
+disk access (e.g. Rugged, `git`, `rm -rf`) anywhere outside
+`lib/gitlab/git`.
+
+The process for adding new Gitaly features is:
+
+- exploration / prototyping
+- design and create a new Gitaly RPC [in gitaly-proto](https://gitlab.com/gitlab-org/gitaly-proto)
+- release a new version of gitaly-proto
+- write implementation and tests for the RPC [in Gitaly](https://gitlab.com/gitlab-org/gitaly), in Go or Ruby
+- release a new version of Gitaly
+- write client code in gitlab-ce/ee, gitlab-workhorse or gitlab-shell that calls the new Gitaly RPC
+
+These steps often overlap. It is possible to use an unreleased version
+of Gitaly and gitaly-proto during testing and development.
+
+- See the [Gitaly repo](https://gitlab.com/gitlab-org/gitaly/blob/master/CONTRIBUTING.md#development-and-testing-with-a-custom-gitaly-proto) for instructions on writing server side code with an unreleased protocol.
+- See [below](#running-tests-with-a-locally-modified-version-of-gitaly) for instructions on running gitlab-ce tests with a modified version of Gitaly.
+- In GDK run `gdk install` and restart `gdk run` (or `gdk run app`) to use a locally modified Gitaly version for development
+
+### Gitaly-ruby
+
+It is possible to implement and test RPC's in Gitaly using Ruby code,
+in
+[gitaly-ruby](https://gitlab.com/gitlab-org/gitaly/tree/master/ruby).
+This should make it easier to contribute for developers who are less
+comfortable writing Go code.
+
+There is documentation for this approach in [the Gitaly
+repo](https://gitlab.com/gitlab-org/gitaly/blob/master/doc/ruby_endpoint.md).
+
+## Modifying existing Git features
+
+If you modify existing Git features in `lib/gitlab/git` you need to make
+sure the changes also work in Gitaly. Because we are still in the
+migration process there are a number of subtle pitfalls. Features that
+have been migrated have dual implementations (Gitaly and local). The
+Gitaly implementation may or may not use a vendored (and therefore
+possibly outdated) copy of the local implementation in `lib/gitlab/git`.
+
+To avoid unexpected problems and conflicts, all changes to
+`lib/gitlab/git` need to be approved by a member of the Gitaly team.
+
+For the time being, while the Gitaly migration is still in progress,
+there should be no Enterprise Edition-only Git code in
+`lib/gitlab/git`. Also no mixins.
+
 ## Feature Flags
 
 Gitaly makes heavy use of [feature flags](feature_flags.md).
@@ -99,10 +160,14 @@ end
 
 ## Running tests with a locally modified version of Gitaly
 
-Normally, gitlab-ce/ee tests use a local clone of Gitaly in `tmp/tests/gitaly`
-pinned at the version specified in GITALY_SERVER_VERSION. If you want
-to run tests locally against a modified version of Gitaly you can
-replace `tmp/tests/gitaly` with a symlink.
+Normally, gitlab-ce/ee tests use a local clone of Gitaly in
+`tmp/tests/gitaly` pinned at the version specified in
+`GITALY_SERVER_VERSION`. The `GITALY_SERVER_VERSION` file supports
+`=my-branch` syntax to use a custom branch in gitlab-org/gitaly. If
+you want to run tests locally against a modified version of Gitaly you
+can replace `tmp/tests/gitaly` with a symlink. This is much faster
+because the `=my-branch` syntax forces a Gitaly re-install each time
+you run `rspec`.
 
 ```shell
 rm -rf tmp/tests/gitaly
diff --git a/doc/development/gotchas.md b/doc/development/gotchas.md
index 5786287d00c..d25d856c3a3 100644
--- a/doc/development/gotchas.md
+++ b/doc/development/gotchas.md
@@ -92,6 +92,54 @@ describe API::Labels do
 end
 ```
 
+## Avoid using `allow_any_instance_of` in RSpec
+
+### Why
+
+* Because it is not isolated therefore it might be broken at times.
+* Because it doesn't work whenever the method we want to stub was defined
+  in a prepended module, which is very likely the case in EE. We could see
+  error like this:
+
+        1.1) Failure/Error: allow_any_instance_of(ApplicationSetting).to receive_messages(messages)
+               Using `any_instance` to stub a method (elasticsearch_indexing) that has been defined on a prepended module (EE::ApplicationSetting) is not supported.
+
+### Alternative: `expect_next_instance_of`
+
+Instead of writing:
+
+```ruby
+# Don't do this:
+allow_any_instance_of(Project).to receive(:add_import_job)
+```
+
+We could write:
+
+```ruby
+# Do this:
+expect_next_instance_of(Project) do |project|
+  expect(project).to receive(:add_import_job)
+end
+```
+
+If we also want to expect the instance was initialized with some particular
+arguments, we could also pass it to `expect_next_instance_of` like:
+
+```ruby
+# Do this:
+expect_next_instance_of(MergeRequests::RefreshService, project, user) do |refresh_service|
+  expect(refresh_service).to receive(:execute).with(oldrev, newrev, ref)
+end
+```
+
+This would expect the following:
+
+```ruby
+# Above expects:
+refresh_service = MergeRequests::RefreshService.new(project, user)
+refresh_service.execute(oldrev, newrev, ref)
+```
+
 ## Do not `rescue Exception`
 
 See ["Why is it bad style to `rescue Exception => e` in Ruby?"][Exception].
diff --git a/doc/development/i18n/externalization.md b/doc/development/i18n/externalization.md
index 856ef882453..4ba9958e2c6 100644
--- a/doc/development/i18n/externalization.md
+++ b/doc/development/i18n/externalization.md
@@ -131,6 +131,9 @@ There is also and alternative method to [translate messages from validation erro
 
 ### Interpolation
 
+Placeholders in translated text should match the code style of the respective source file.
+For example use `%{created_at}` in Ruby but `%{createdAt}` in JavaScript.
+
 - In Ruby/HAML:
 
     ```ruby
@@ -141,11 +144,19 @@ There is also and alternative method to [translate messages from validation erro
 
     ```js
     import { __, sprintf } from '~/locale';
-    sprintf(__('Hello %{username}'), { username: 'Joe' }) => 'Hello Joe'
+
+    sprintf(__('Hello %{username}'), { username: 'Joe' }); // => 'Hello Joe'
     ```
 
-The placeholders should match the code style of the respective source file.
-For example use `%{created_at}` in Ruby but `%{createdAt}` in JavaScript.
+    By default, `sprintf` escapes the placeholder values.
+    If you want to take care of that yourself, you can pass `false` as third argument.
+
+    ```js
+    import { __, sprintf } from '~/locale';
+
+    sprintf(__('This is %{value}'), { value: '<strong>bold</strong>' }); // => 'This is &lt;strong&gt;bold&lt;/strong&gt;'
+    sprintf(__('This is %{value}'), { value: '<strong>bold</strong>' }, false); // => 'This is <strong>bold</strong>'
+    ```
 
 ### Plurals
 
@@ -222,7 +233,7 @@ This makes use of [`Intl.DateTimeFormat`].
 Please never split a sentence as that would assume the sentence grammar and
 structure is the same in all languages.
 
-For instance, the following
+For instance, the following:
 
 ```js
 {{ s__("mrWidget|Set by") }}
@@ -236,6 +247,27 @@ should be externalized as follows:
 {{ sprintf(s__("mrWidget|Set by %{author} to be merged automatically when the pipeline succeeds"), { author: author.name }) }}
 ```
 
+#### Avoid splitting sentences when adding links
+
+This also applies when using links in between translated sentences, otherwise these texts are not translatable in certain languages.
+
+Instead of:
+
+```haml
+- zones_link = link_to(s_('ClusterIntegration|zones'), 'https://cloud.google.com/compute/docs/regions-zones/regions-zones', target: '_blank', rel: 'noopener noreferrer')
+= s_('ClusterIntegration|Learn more about %{zones_link}').html_safe % { zones_link: zones_link }
+```
+
+Set the link starting and ending HTML fragments as variables like so:
+
+```haml
+- zones_link_url = 'https://cloud.google.com/compute/docs/regions-zones/regions-zones'
+- zones_link_start = '<a href="%{url}" target="_blank" rel="noopener noreferrer">'.html_safe % { url: zones_link_url }
+= s_('ClusterIntegration|Learn more about %{zones_link_start}zones%{zones_link_end}').html_safe % { zones_link_start: zones_link_start, zones_link_end: '</a>'.html_safe }
+```
+
+The reasoning behind this is that in some languages words change depending on context. For example in Japanese は is added to the subject of a sentence and を to the object. This is impossible to translate correctly if we extract individual words from the sentence.
+
 When in doubt, try to follow the best practices described in this [Mozilla
 Developer documentation][mdn].
 
@@ -259,7 +291,7 @@ If there are merge conflicts in the `gitlab.pot` file, you can delete the file
 and regenerate it using the same command. Confirm that you are not deleting any strings accidentally by looking over the diff.
 
 The command also updates the translation files for each language: `locale/*/gitlab.po`
-These changes can be discarded, the languange files will be updated by Crowdin
+These changes can be discarded, the language files will be updated by Crowdin
 automatically.
 
 Discard all of them at once like this:
diff --git a/doc/development/i18n/proofreader.md b/doc/development/i18n/proofreader.md
index 960eabd5538..9d0d7348df9 100644
--- a/doc/development/i18n/proofreader.md
+++ b/doc/development/i18n/proofreader.md
@@ -10,18 +10,21 @@ are very appreciative of the work done by translators and proofreaders!
   - Huang Tao - [GitLab](https://gitlab.com/htve), [Crowdin](https://crowdin.com/profile/htve)
 - Chinese Traditional
   - Huang Tao - [GitLab](https://gitlab.com/htve), [Crowdin](https://crowdin.com/profile/htve)
+  - Weizhe Ding - [GitLab](https://gitlab.com/d.weizhe), [Crowdin](https://crowdin.com/profile/d.weizhe)
 - Chinese Traditional, Hong Kong
   - Huang Tao - [GitLab](https://gitlab.com/htve), [Crowdin](https://crowdin.com/profile/htve)
 - Dutch
 - Esperanto
 - French
-  - Rémy Coutable - [GitLab](https://gitlab.com/rymai), [Crowdin](https://crowdin.com/profile/rymai)
+  - Davy Defaud - [GitLab](https://gitlab.com/DevDef), [Crowdin](https://crowdin.com/profile/DevDef)
 - German
 - Indonesian
   - Ahmad Naufal Mukhtar - [GitLab](https://gitlab.com/anaufalm), [Crowdin](https://crowdin.com/profile/anaufalm)
 - Italian
   - Paolo Falomo - [GitLab](https://gitlab.com/paolofalomo), [Crowdin](https://crowdin.com/profile/paolo.falomo)
 - Japanese
+  - Yamana Tokiuji - [GitLab](https://gitlab.com/tokiuji), [Crowdin](https://crowdin.com/profile/yamana)
+  - Hiroyuki Sato - [GitLab](https://gitlab.com/hiroponz), [Crowdin](https://crowdin.com/profile/hiroponz)
 - Korean
   - Chang-Ho Cha - [GitLab](https://gitlab.com/changho-cha), [Crowdin](https://crowdin.com/profile/zzazang)
   - Huang Tao - [GitLab](https://gitlab.com/htve), [Crowdin](https://crowdin.com/profile/htve)
@@ -29,6 +32,7 @@ are very appreciative of the work done by translators and proofreaders!
   - Filip Mech - [GitLab](https://gitlab.com/mehenz), [Crowdin](https://crowdin.com/profile/mehenz)
 - Portuguese, Brazilian
   - Paulo George Gomes Bezerra - [GitLab](https://gitlab.com/paulobezerra), [Crowdin](https://crowdin.com/profile/paulogomes.rep)
+  - André Gama - [GitLab](https://gitlab.com/andregamma), [Crowdin](https://crowdin.com/profile/ToeOficial)
 - Russian
   - Nikita Grylov - [GitLab](https://gitlab.com/nixel2007), [Crowdin](https://crowdin.com/profile/nixel2007)
   - Alexy Lustin - [GitLab](https://gitlab.com/allustin), [Crowdin](https://crowdin.com/profile/lustin)
diff --git a/doc/development/img/state-model-issue.png b/doc/development/img/state-model-issue.png
deleted file mode 100644
index ee33b6886c6..00000000000
--- a/doc/development/img/state-model-issue.png
+++ /dev/null
diff --git a/doc/development/img/state-model-legend.png b/doc/development/img/state-model-legend.png
deleted file mode 100644
index 1c121f2588c..00000000000
--- a/doc/development/img/state-model-legend.png
+++ /dev/null
diff --git a/doc/development/img/state-model-merge-request.png b/doc/development/img/state-model-merge-request.png
deleted file mode 100644
index e00da10cac2..00000000000
--- a/doc/development/img/state-model-merge-request.png
+++ /dev/null
diff --git a/doc/development/merge_request_performance_guidelines.md b/doc/development/merge_request_performance_guidelines.md
index 2b4126b43ef..12badbe39b2 100644
--- a/doc/development/merge_request_performance_guidelines.md
+++ b/doc/development/merge_request_performance_guidelines.md
@@ -162,7 +162,7 @@ need for running complex operations to fetch the data. You should use Redis if
 data should be cached for a certain time period instead of the duration of the
 transaction.
 
-For example, say you process multiple snippets of text containiner username
+For example, say you process multiple snippets of text containing username
 mentions (e.g. `Hello @alice` and `How are you doing @alice?`). By caching the
 user objects for every username we can remove the need for running the same
 query for every mention of `@alice`.
diff --git a/doc/development/new_fe_guide/dependencies.md b/doc/development/new_fe_guide/dependencies.md
index 3417d77a06d..12a4f089d41 100644
--- a/doc/development/new_fe_guide/dependencies.md
+++ b/doc/development/new_fe_guide/dependencies.md
@@ -1,3 +1,20 @@
 # Dependencies
 
-> TODO: Add Dependencies
\ No newline at end of file
+## Adding Dependencies.
+
+GitLab uses `yarn` to manage dependencies. These dependencies are defined in
+two groups within `package.json`, `dependencies` and `devDependencies`. For
+our purposes, we consider anything that is required to compile our production
+assets a "production" dependency. That is, anything required to run the
+`webpack` script with `NODE_ENV=production`. Tools like `eslint`, `karma`, and
+various plugins and tools used in development are considered `devDependencies`.
+This distinction is used by omnibus to determine which dependencies it requires
+when building GitLab.
+
+Exceptions are made for some tools that we require in the
+`gitlab:assets:compile` CI job such as `webpack-bundle-analyzer` to analyze our
+production assets post-compile.
+
+---
+
+> TODO: Add Dependencies
diff --git a/doc/development/new_fe_guide/development/accessibility.md b/doc/development/new_fe_guide/development/accessibility.md
index ed35f08432f..2a3a126ca5c 100644
--- a/doc/development/new_fe_guide/development/accessibility.md
+++ b/doc/development/new_fe_guide/development/accessibility.md
@@ -1,3 +1,48 @@
-# Accessibility
+# Accessiblity
+Using semantic HTML plays a key role when it comes to accessibility.
 
-> TODO: Add content
+## Accessible Rich Internet Applications - ARIA
+WAI-ARIA, the Accessible Rich Internet Applications specification, defines a way to make Web content and Web applications more accessible to people with disabilities. 
+
+> Note: It is [recommended][using-aria] to use semantic elements as the primary method to achieve accessibility rather than adding aria attributes. Adding aria attributes should be seen as a secondary method for creating accessible elements.
+
+### Role
+The `role` attribute describes the role the element plays in the context of the document.
+
+Check the list of WAI-ARIA roles [here][roles]
+
+## Icons
+When using icons or images that aren't absolutely needed to understand the context, we should use `aria-hidden="true"`.
+
+On the other hand, if an icon is crucial to understand the context we should do one of the following:
+1. Use `aria-label` in the element with a meaningful description
+1. Use `aria-labelledby` to point to an element that contains the explanation for that icon
+
+## Form inputs
+In forms we should use the `for` attribute in the label statement:
+```
+<div>
+  <label for="name">Fill in your name:</label>
+  <input type="text" id="name" name="name">
+</div>
+```
+
+## Testing
+
+1. On MacOS you can use [VoiceOver][voice-over] by pressing `cmd+F5`.
+1. On Windows you can use [Narrator][narrator] by pressing Windows logo key + Ctrl + Enter.
+
+## Online resources
+
+- [Chrome Accessibility Developer Tools][dev-tools] for testing accessibility
+- [Audit Rules Page][audit-rules] for best practices
+- [Lighthouse Accessibility Score][lighthouse] for accessibility audits
+
+[using-aria]: https://www.w3.org/TR/using-aria/#notes2
+[dev-tools]: https://github.com/GoogleChrome/accessibility-developer-tools
+[audit-rules]: https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules
+[aria-w3c]: https://www.w3.org/TR/wai-aria-1.1/
+[roles]: https://www.w3.org/TR/wai-aria-1.1/#landmark_roles
+[voice-over]: https://www.apple.com/accessibility/mac/vision/
+[narrator]: https://www.microsoft.com/en-us/accessibility/windows
+[lighthouse]: https://developers.google.com/web/tools/lighthouse/scoring#a11y
diff --git a/doc/development/new_fe_guide/development/components.md b/doc/development/new_fe_guide/development/components.md
index 637099d1e83..899efb398cd 100644
--- a/doc/development/new_fe_guide/development/components.md
+++ b/doc/development/new_fe_guide/development/components.md
@@ -1,3 +1,21 @@
 # Components
 
-> TODO: Add content
+## Graphs
+
+We have a lot of graphing libraries in our codebase to render graphs. In an effort to improve maintainability, new graphs should use [D3.js](https://d3js.org/). If a new graph is fairly simple, consider implementing it in SVGs or HTML5 canvas.
+
+We chose D3 as our library going forward because of the following features:
+
+* [Tree shaking webpack capabilities.](https://github.com/d3/d3/blob/master/CHANGES.md#changes-in-d3-40)
+* [Compatible with vue.js as well as vanilla javascript.](https://github.com/d3/d3/blob/master/CHANGES.md#changes-in-d3-40)
+
+D3 is very popular across many projects outside of GitLab:
+
+* [The New York Times](https://archive.nytimes.com/www.nytimes.com/interactive/2012/02/13/us/politics/2013-budget-proposal-graphic.html)
+* [plot.ly](https://plot.ly/)
+* [Droptask](https://www.droptask.com/)
+
+Within GitLab, D3 has been used for the following notable features
+
+* [Prometheus graphs](https://docs.gitlab.com/ee/user/project/integrations/prometheus.html)
+* Contribution calendars
diff --git a/doc/development/new_fe_guide/development/testing.md b/doc/development/new_fe_guide/development/testing.md
index c359bd83ed1..e1e13474b75 100644
--- a/doc/development/new_fe_guide/development/testing.md
+++ b/doc/development/new_fe_guide/development/testing.md
@@ -1,3 +1,135 @@
-# Testing
+# Overview of Frontend Testing
 
-> TODO: Add content
+## Types of tests in our codebase
+
+* **RSpec**
+  * **[Ruby unit tests](#ruby-unit-tests-spec-rb)** for models, controllers, helpers, etc. (`/spec/**/*.rb`)
+  * **[Full feature tests](#full-feature-tests-spec-features-rb)** (`/spec/features/**/*.rb`)
+* **[Karma](#karma-tests-spec-javascripts-js)** (`/spec/javascripts/**/*.js`)
+* ~~Spinach~~ — These have been removed from our codebase in May 2018. (`/features/`)
+
+## RSpec: Ruby unit tests `/spec/**/*.rb`
+
+These tests are meant to unit test the ruby models, controllers and helpers.
+
+### When do we write/update these tests?
+
+Whenever we create or modify any Ruby models, controllers or helpers we add/update corresponding tests.
+
+---
+
+## RSpec: Full feature tests `/spec/features/**/*.rb`
+
+Full feature tests will load a full app environment and allow us to test things like rendering DOM, interacting with links and buttons, testing the outcome of those interactions through multiple pages if necessary. These are also called end-to-end tests but should not be confused with QA end-to-end tests (`package-and-qa` manual pipeline job).
+
+### When do we write/update these tests?
+
+When we add a new feature, we write at least two tests covering the success and the failure scenarios.
+
+### Relevant notes
+
+A `:js` flag is added to the test to make sure the full environment is loaded.
+
+```
+scenario 'successfully', :js do
+  sign_in(create(:admin))
+end
+```
+
+The steps of each test are written using capybara methods ([documentation](http://www.rubydoc.info/gems/capybara/2.15.1)).
+
+Bear in mind <abbr title="XMLHttpRequest">XHR</abbr> calls might require you to use `wait_for_requests` in between steps, like so:
+
+```rspec
+find('.form-control').native.send_keys(:enter)
+
+wait_for_requests
+
+expect(page).not_to have_selector('.card')
+```
+
+---
+
+## Karma tests `/spec/javascripts/**/*.js`
+
+These are the more frontend-focused, at the moment. They're **faster** than `rspec` and make for very quick testing of frontend components.
+
+### When do we write/update these tests?
+
+When we add/update a method/action/mutation to Vue or Vuex, we write karma tests to ensure the logic we wrote doesn't break. We should, however, refrain from writing tests that double-test Vue's internal features.
+
+### Relevant notes
+
+Karma tests are run against a virtual DOM.
+
+To populate the DOM, we can use fixtures to fake the generation of HTML instead of having Rails do that.
+
+Be sure to check the [best practices for karma tests](../../testing_guide/frontend_testing.html#best-practices).
+
+### Vue and Vuex
+
+Test as much as possible without double-testing Vue's internal features, as mentioned above.
+
+Make sure to test computedProperties, mutations, actions. Run the action and test that the proper mutations are committed.
+
+Also check these [notes on testing Vue components](../../fe_guide/vue.html#testing-vue-components).
+
+#### Vuex Helper: `testAction`
+
+We have a helper available to make testing actions easier, as per [official documentation](https://vuex.vuejs.org/en/testing.html):
+
+```
+testAction(
+  actions.actionName, // action
+  { }, // params to be passed to action
+  state, // state
+  [
+    { type: types.MUTATION},
+    { type: types.MUTATION_1, payload: {}},
+  ], // mutations committed
+  [
+    { type: 'actionName', payload: {}},
+    { type: 'actionName1', payload: {}},
+  ] // actions dispatched
+  done,
+);
+```
+
+Check an example in [spec/javascripts/ide/stores/actions_spec.jsspec/javascripts/ide/stores/actions_spec.js](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/spec/javascripts/ide/stores/actions_spec.js).
+
+#### Vue Helper: `mountComponent`
+
+To make mounting a Vue component easier and more readable, we have a few helpers available in `spec/helpers/vue_mount_component_helper`.
+
+* `createComponentWithStore`
+* `mountComponentWithStore`
+
+Examples of usage:
+
+```
+beforeEach(() => {
+  vm = createComponentWithStore(Component, store);
+
+  vm.$store.state.currentBranchId = 'master';
+
+  vm.$mount();
+},
+```
+
+```
+beforeEach(() => {
+  vm = mountComponentWithStore(Component, {
+    el: '#dummy-element',
+    store,
+    props: { badge },
+  });
+},
+```
+
+Don't forget to clean up:
+
+```
+afterEach(() => {
+  vm.$destroy();
+});
+```
diff --git a/doc/development/new_fe_guide/style/javascript.md b/doc/development/new_fe_guide/style/javascript.md
index 480d50a211f..57efd9353bc 100644
--- a/doc/development/new_fe_guide/style/javascript.md
+++ b/doc/development/new_fe_guide/style/javascript.md
@@ -1,3 +1,195 @@
 # JavaScript style guide
 
-> TODO: Add content
+We use [Airbnb's JavaScript Style Guide][airbnb-style-guide] and it's accompanying linter to manage most of our JavaScript style guidelines.
+
+In addition to the style guidelines set by Airbnb, we also have a few specific rules listed below.
+
+> **Tip:**
+You can run eslint locally by running `yarn eslint`
+
+## Arrays
+
+<a name="avoid-foreach"></a><a name="1.1"></a>
+- [1.1](#avoid-foreach) **Avoid ForEach when mutating data** Use `map`, `reduce` or `filter` instead of `forEach` when mutating data. This will minimize mutations in functions ([which is aligned with Airbnb's style guide][airbnb-minimize-mutations])
+
+```
+// bad
+users.forEach((user, index) => {
+  user.id = index;
+});
+
+// good
+const usersWithId = users.map((user, index) => {
+  return Object.assign({}, user, { id: index });
+});
+```
+
+## Functions
+
+<a name="limit-params"></a><a name="2.1"></a>
+- [2.1](#limit-params) **Limit number of parameters** If your function or method has more than 3 parameters, use an object as a parameter instead.
+
+```
+// bad
+function a(p1, p2, p3) {
+  // ...
+};
+
+// good
+function a(p) {
+  // ...
+};
+```
+
+## Classes & constructors
+
+<a name="avoid-constructor-side-effects"></a><a name="3.1"></a>
+- [3.1](#avoid-constructor-side-effects) **Avoid side effects in constructors** Avoid making some operations in the `constructor`, such as asynchronous calls, API requests and DOM manipulations. Prefer moving them into separate functions. This will make tests easier to write and code easier to maintain.
+
+  ```javascript
+  // bad
+  class myClass {
+    constructor(config) {
+      this.config = config;
+      axios.get(this.config.endpoint)
+    }
+  }
+
+  // good
+  class myClass {
+    constructor(config) {
+      this.config = config;
+    }
+
+    makeRequest() {
+      axios.get(this.config.endpoint)
+    }
+  }
+  const instance = new myClass();
+  instance.makeRequest();
+
+  ```
+
+<a name="avoid-classes-to-handle-dom-events"></a><a name="3.2"></a>
+- [3.2](#avoid-classes-to-handle-dom-events) **Avoid classes to handle DOM events** If the only purpose of the class is to bind a DOM event and handle the callback, prefer using a function.
+
+```
+// bad
+class myClass {
+  constructor(config) {
+    this.config = config;
+  }
+
+  init() {
+    document.addEventListener('click', () => {});
+  }
+}
+
+// good
+
+const myFunction = () => {
+  document.addEventListener('click', () => {
+    // handle callback here
+  });
+}
+```
+
+<a name="element-container"></a><a name="3.3"></a>
+- [3.3](#element-container) **Pass element container to constructor** When your class manipulates the DOM, receive the element container as a parameter.
+This is more maintainable and performant.
+
+```
+// bad
+class a {
+  constructor() {
+    document.querySelector('.b');
+  }
+}
+
+// good
+class a {
+  constructor(options) {
+    options.container.querySelector('.b');
+  }
+}
+```
+
+## Type Casting & Coercion
+
+<a name="use-parseint"></a><a name="4.1"></a>
+- [4.1](#use-parseint) **Use ParseInt** Use `ParseInt` when converting a numeric string into a number.
+
+```
+// bad
+Number('10')
+
+
+// good
+parseInt('10', 10);
+```
+
+## CSS Selectors
+
+<a name="use-js-prefix"></a><a name="5.1"></a>
+- [5.1](#use-js-prefix) **Use js prefix** If a CSS class is only being used in JavaScript as a reference to the element, prefix the class name with `js-`
+
+```
+// bad
+<button class="add-user"></button>
+
+// good
+<button class="js-add-user"></button>
+```
+
+## Modules
+
+<a name="use-absolute-paths"></a><a name="6.1"></a>
+- [6.1](#use-absolute-paths) **Use absolute paths for nearby modules** Use absolute paths if the module you are importing is less than two levels up.
+
+```
+// bad
+import GitLabStyleGuide from '~/guides/GitLabStyleGuide';
+
+// good
+import GitLabStyleGuide from '../GitLabStyleGuide';
+```
+
+<a name="use-relative-paths"></a><a name="6.2"></a>
+- [6.2](#use-relative-paths) **Use relative paths for distant modules** If the module you are importing is two or more levels up, use a relative path instead of an absolute path.
+
+```
+// bad
+import GitLabStyleGuide from '../../../guides/GitLabStyleGuide';
+
+// good
+import GitLabStyleGuide from '~/GitLabStyleGuide';
+```
+
+<a name="global-namespace"></a><a name="6.3"></a>
+- [6.3](#global-namespace) **Do not add to global namespace**
+
+<a name="domcontentloaded"></a><a name="6.4"></a>
+- [6.4](#domcontentloaded) **Do not use DOMContentLoaded in non-page modules** Imported modules should act the same each time they are loaded. `DOMContentLoaded` events are only allowed on modules loaded in the `/pages/*` directory because those are loaded dynamically with webpack.
+
+## Security
+
+<a name="avoid-xss"></a><a name="7.1"></a>
+- [7.1](#avoid-xss) **Avoid XSS** Do not use `innerHTML`, `append()` or `html()` to set content. It opens up too many vulnerabilities.
+
+## ESLint
+
+<a name="disable-eslint-file"></a><a name="8.1"></a>
+- [8.1](#disable-eslint-file) **Disabling ESLint in new files** Do not disable ESLint when creating new files. Existing files may have existing rules disabled due to legacy compatibility reasons but they are in the process of being refactored.
+
+<a name="disable-eslint-rule"></a><a name="8.2"></a>
+- [8.2](#disable-eslint-rule) **Disabling ESLint rule** Do not disable specific ESLint rules. Due to technical debt, you may disable the following rules only if you are invoking/instantiating existing code modules
+
+  - [no-new][no-new]
+  - [class-method-use-this][class-method-use-this]
+
+> Note: Disable these rules on a per line basis. This makes it easier to refactor in the future. E.g. use `eslint-disable-next-line` or `eslint-disable-line`
+
+[airbnb-style-guide]: https://github.com/airbnb/javascript
+[airbnb-minimize-mutations]: https://github.com/airbnb/javascript#testing--for-real
+[no-new]: http://eslint.org/docs/rules/no-new
+[class-method-use-this]: http://eslint.org/docs/rules/class-methods-use-this
diff --git a/doc/development/new_fe_guide/style/prettier.md b/doc/development/new_fe_guide/style/prettier.md
index eb18189282b..6395af6f815 100644
--- a/doc/development/new_fe_guide/style/prettier.md
+++ b/doc/development/new_fe_guide/style/prettier.md
@@ -43,3 +43,17 @@ yarn prettier-all-save
 Formats all files in the repository with Prettier. (This should only be used to test global rule updates otherwise you would end up with huge MR's).
 
 The source of these Yarn scripts can be found in `/scripts/frontend/prettier.js`.
+
+### Scripts during Conversion period
+
+```
+node ./scripts/frontend/prettier.js check ./vendor/
+```
+
+This will go over all files in a specific folder check it.
+
+```
+node ./scripts/frontend/prettier.js save ./vendor/
+```
+
+This will go over all files in a specific folder and save it.
diff --git a/doc/development/new_fe_guide/tips.md b/doc/development/new_fe_guide/tips.md
index f0cdf52d618..881ad1662ae 100644
--- a/doc/development/new_fe_guide/tips.md
+++ b/doc/development/new_fe_guide/tips.md
@@ -1,3 +1,9 @@
 # Tips
 
-> TODO: Add tips
+## Clearing production compiled assets
+
+To clear production compiled assets created with `yarn webpack-prod` you can run:
+
+```
+yarn clean
+```
diff --git a/doc/development/object_state_models.md b/doc/development/object_state_models.md
deleted file mode 100644
index 623bbf143ef..00000000000
--- a/doc/development/object_state_models.md
+++ /dev/null
@@ -1,25 +0,0 @@
-# Object state models
-
-## Diagrams
-
-[GitLab object state models](https://drive.google.com/drive/u/3/folders/0B5tDlHAM4iZINmpvYlJXcDVqMGc)
-
----
-
-## Legend
-
-![legend](img/state-model-legend.png)
-
---- 
-
-## Issue
-
-[`app/models/issue.rb`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/models/issue.rb)
-![issue](img/state-model-issue.png)
-
---- 
-
-## Merge request
-
-[`app/models/merge_request.rb`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/models/merge_request.rb)
-![merge request](img/state-model-merge-request.png)
\ No newline at end of file
diff --git a/doc/development/ordering_table_columns.md b/doc/development/ordering_table_columns.md
index 249e70c7b0e..5d00e1f7a0c 100644
--- a/doc/development/ordering_table_columns.md
+++ b/doc/development/ordering_table_columns.md
@@ -30,7 +30,7 @@ example) at the end.
 
 ## Type Sizes
 
-While the PostgreSQL docuemntation
+While the PostgreSQL documentation
 (https://www.postgresql.org/docs/current/static/datatype.html) contains plenty
 of information we will list the sizes of common types here so it's easier to
 look them up. Here "word" refers to the word size, which is 4 bytes for a 32
diff --git a/doc/development/query_recorder.md b/doc/development/query_recorder.md
index 12e90101139..2167ed57428 100644
--- a/doc/development/query_recorder.md
+++ b/doc/development/query_recorder.md
@@ -2,7 +2,7 @@
 
 QueryRecorder is a tool for detecting the [N+1 queries problem](http://guides.rubyonrails.org/active_record_querying.html#eager-loading-associations) from tests.
 
-> Implemented in [spec/support/query_recorder.rb](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/spec/support/query_recorder.rb) via [9c623e3e](https://gitlab.com/gitlab-org/gitlab-ce/commit/9c623e3e5d7434f2e30f7c389d13e5af4ede770a)
+> Implemented in [spec/support/query_recorder.rb](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/spec/support/helpers/query_recorder.rb) via [9c623e3e](https://gitlab.com/gitlab-org/gitlab-ce/commit/9c623e3e5d7434f2e30f7c389d13e5af4ede770a)
 
 As a rule, merge requests [should not increase query counts](merge_request_performance_guidelines.md#query-counts). If you find yourself adding something like `.includes(:author, :assignee)` to avoid having `N+1` queries, consider using QueryRecorder to enforce this with a test. Without this, a new feature which causes an additional model to be accessed will silently reintroduce the problem.
 
@@ -22,6 +22,20 @@ As an example you might create 5 issues in between counts, which would cause the
 
 > **Note:** In some cases the query count might change slightly between runs for unrelated reasons. In this case you might need to test `exceed_query_limit(control_count + acceptable_change)`, but this should be avoided if possible.
 
+## Cached queries
+
+By default, QueryRecorder will ignore cached queries in the count. However, it may be better to count
+all queries to avoid introducing an N+1 query that may be masked by the statement cache. To do this,
+pass the `skip_cached` variable to `QueryRecorder` and use the `exceed_all_query_limit` matcher:
+
+```
+it "avoids N+1 database queries" do
+  control_count = ActiveRecord::QueryRecorder.new(skip_cached: false) { visit_some_page }.count
+  create_list(:issue, 5)
+  expect { visit_some_page }.not_to exceed_all_query_limit(control_count)
+end
+```
+
 ## Finding the source of the query
 
 It may be useful to identify the source of the queries by looking at the call backtrace.
diff --git a/doc/development/rake_tasks.md b/doc/development/rake_tasks.md
index fdfa1f10402..fc51b74da1d 100644
--- a/doc/development/rake_tasks.md
+++ b/doc/development/rake_tasks.md
@@ -65,12 +65,11 @@ To make sure that indices still fit. You could find great details in:
 ## Run tests
 
 In order to run the test you can use the following commands:
-- `rake spinach` to run the spinach suite
 - `rake spec` to run the rspec suite
 - `rake karma` to run the karma test suite
 - `rake gitlab:test` to run all the tests
 
-Note: Both `rake spinach` and `rake spec` takes significant time to pass.
+Note: `rake spec` takes significant time to pass.
 Instead of running full test suite locally you can save a lot of time by running
 a single test or directory related to your changes. After you submit merge request
 CI will run full test suite for you. Green CI status in the merge request means
@@ -82,12 +81,10 @@ files it can find, also the ones in `/tmp`
 To run a single test file you can use:
 
 - `bin/rspec spec/controllers/commit_controller_spec.rb` for a rspec test
-- `bin/spinach features/project/issues/milestones.feature` for a spinach test
 
 To run several tests inside one directory:
 
 - `bin/rspec spec/requests/api/` for the rspec tests if you want to test API only
-- `bin/spinach features/profile/` for the spinach tests if you want to test only profile pages
 
 ### Speed-up tests, rake tasks, and migrations
 
@@ -179,3 +176,20 @@ git push -u origin update-project-templates
 ```
 
 Now create a merge request and merge that to master.
+
+## Generate route lists
+
+To see the full list of API routes, you can run:
+
+```shell
+bundle exec rake grape:path_helpers
+```
+
+For the Rails controllers, run:
+
+```shell
+bundle exec rake routes
+```
+
+Since these take some time to create, it's often helpful to save the output to
+a file for quick reference.
diff --git a/doc/development/testing_guide/best_practices.md b/doc/development/testing_guide/best_practices.md
index df80cd9f584..1a926a660f1 100644
--- a/doc/development/testing_guide/best_practices.md
+++ b/doc/development/testing_guide/best_practices.md
@@ -12,8 +12,7 @@ Here are some things to keep in mind regarding test performance:
 - `FactoryBot.build(...)` and `.build_stubbed` are faster than `.create`.
 - Don't `create` an object when `build`, `build_stubbed`, `attributes_for`,
   `spy`, or `double` will do. Database persistence is slow!
-- Don't mark a feature as requiring JavaScript (through `@javascript` in
-  Spinach or `:js` in RSpec) unless it's _actually_ required for the test
+- Don't mark a feature as requiring JavaScript (through `:js` in RSpec) unless it's _actually_ required for the test
   to be valid. Headless browser testing is slow!
 
 [parallelization]: ci.md#test-suite-parallelization-on-the-ci
@@ -63,6 +62,8 @@ writing one](testing_levels.md#consider-not-writing-a-system-test)!
 
 Sometimes you may need to debug Capybara tests by observing browser behavior.
 
+#### Live debug
+
 You can pause Capybara and view the website on the browser by using the
 `live_debug` method in your spec. The current page will be automatically opened
 in your default browser.
@@ -90,6 +91,71 @@ Finished in 34.51 seconds (files took 0.76702 seconds to load)
 
 Note: `live_debug` only works on javascript enabled specs.
 
+#### Run `:js` spec in a visible browser
+
+Run the spec with `CHROME_HEADLESS=0`, e.g.:
+
+```
+CHROME_HEADLESS=0 bundle exec rspec some_spec.rb
+```
+
+The test will go by quickly, but this will give you an idea of what's happening.
+
+You can also add `byebug` or `binding.pry` to pause execution and step through
+the test.
+
+#### Screenshots
+
+We use the `capybara-screenshot` gem to automatically take a screenshot on
+failure. In CI you can download these files as job artifacts.
+
+Also, you can manually take screenshots at any point in a test by adding the
+methods below. Be sure to remove them when they are no longer needed! See
+https://github.com/mattheworiordan/capybara-screenshot#manual-screenshots for
+more.
+
+Add `screenshot_and_save_page` in a `:js` spec to screenshot what Capybara
+"sees", and save the page source.
+
+Add `screenshot_and_open_image` in a `:js` spec to screenshot what Capybara
+"sees", and automatically open the image.
+
+The HTML dumps created by this are missing CSS.
+This results in them looking very different from the actual application.
+There is a [small hack](https://gitlab.com/gitlab-org/gitlab-ce/snippets/1718469) to add CSS which makes debugging easier.
+
+### Fast unit tests
+
+Some classes are well-isolated from Rails and you should be able to test them
+without the overhead added by the Rails environment and Bundler's `:default`
+group's gem loading. In these cases, you can `require 'fast_spec_helper'`
+instead of `require 'spec_helper'` in your test file, and your test should run
+really fast since:
+
+- Gems loading is skipped
+- Rails app boot is skipped
+- gitlab-shell and Gitaly setup are skipped
+- Test repositories setup are skipped
+
+`fast_spec_helper` also support autoloading classes that are located inside the
+`lib/` directory. It means that as long as your class / module is using only
+code from the `lib/` directory you will not need to explicitly load any
+dependencies. `fast_spec_helper` also loads all ActiveSupport extensions,
+including core extensions that are commonly used in the Rails environment.
+
+Note that in some cases, you might still have to load some dependencies using
+`require_dependency` when a code is using gems or a dependency is not located
+in `lib/`.
+
+For example, if you want to test your code that is calling the
+`Gitlab::UntrustedRegexp` class, which under the hood uses `re2` library, you
+should either add `require_dependency 're2'` to files in your library that
+need `re2` gem, to make this requirement explicit, or you can add it to the
+spec itself, but the former is preferred.
+
+It takes around one second to load tests that are using `fast_spec_helper`
+instead of 30+ seconds in case of a regular `spec_helper`.
+
 ### `let` variables
 
 GitLab's RSpec suite has made extensive use of `let` variables to reduce
@@ -180,6 +246,11 @@ describe "#==" do
 end
 ```
 
+### Prometheus tests
+
+Prometheus metrics may be preserved from one test run to another. To ensure that metrics are
+reset before each example, add the `:prometheus` tag to the Rspec test.
+
 ### Matchers
 
 Custom matchers should be created to clarify the intent and/or hide the
@@ -281,14 +352,13 @@ All fixtures should be be placed under `spec/fixtures/`.
 
 RSpec config files are files that change the RSpec config (i.e.
 `RSpec.configure do |config|` blocks). They should be placed under
-`spec/support/config/`.
+`spec/support/`.
 
 Each file should be related to a specific domain, e.g.
-`spec/support/config/capybara.rb`, `spec/support/config/carrierwave.rb`, etc.
+`spec/support/capybara.rb`, `spec/support/carrierwave.rb`, etc.
 
-Helpers can be included in the `spec/support/config/rspec.rb` file. If a
-helpers module applies only to a certain kind of specs, it should add modifiers
-to the `config.include` call. For instance if
+If a helpers module applies only to a certain kind of specs, it should add
+modifiers to the `config.include` call. For instance if
 `spec/support/helpers/cycle_analytics_helpers.rb` applies to `:lib` and
 `type: :model` specs only, you would write the following:
 
@@ -299,6 +369,14 @@ RSpec.configure do |config|
 end
 ```
 
+If a config file only consists of `config.include`, you can add these
+`config.include` directly in `spec/spec_helper.rb`.
+
+For very generic helpers, consider including them in the `spec/support/rspec.rb`
+file which is used by the `spec/fast_spec_helper.rb` file. See
+[Fast unit tests](#fast-unit-tests) for more details about the
+`spec/fast_spec_helper.rb` file.
+
 ---
 
 [Return to Testing documentation](index.md)
diff --git a/doc/development/testing_guide/ci.md b/doc/development/testing_guide/ci.md
index e90de55068d..0d8e150e090 100644
--- a/doc/development/testing_guide/ci.md
+++ b/doc/development/testing_guide/ci.md
@@ -24,8 +24,7 @@ Our current CI parallelization setup is as follows:
   uploaded to S3.
 
 After that, the next pipeline will use the up-to-date
-`knapsack/${CI_PROJECT_NAME}/rspec_report-master.json` file. The same strategy
-is used for Spinach tests as well.
+`knapsack/${CI_PROJECT_NAME}/rspec_report-master.json` file. 
 
 ### Monitoring
 
diff --git a/doc/development/testing_guide/end_to_end_tests.md b/doc/development/testing_guide/end_to_end_tests.md
index d10a797a142..21ec926414d 100644
--- a/doc/development/testing_guide/end_to_end_tests.md
+++ b/doc/development/testing_guide/end_to_end_tests.md
@@ -67,9 +67,9 @@ and examples in [the `qa/` directory][instance-qa-examples].
 
 ## Where can I ask for help?
 
-You can ask question in the `#qa` channel on Slack (GitLab internal) or you can
-find an issue you would like to work on in [the issue tracker][gitlab-qa-issues]
-and start a new discussion there.
+You can ask question in the `#quality` channel on Slack (GitLab internal) or
+you can find an issue you would like to work on in
+[the issue tracker][gitlab-qa-issues] and start a new discussion there.
 
 [omnibus-gitlab]: https://gitlab.com/gitlab-org/omnibus-gitlab
 [gitlab-qa]: https://gitlab.com/gitlab-org/gitlab-qa
diff --git a/doc/development/testing_guide/frontend_testing.md b/doc/development/testing_guide/frontend_testing.md
index 0c63f51cb45..3b2b9c8c947 100644
--- a/doc/development/testing_guide/frontend_testing.md
+++ b/doc/development/testing_guide/frontend_testing.md
@@ -62,6 +62,7 @@ describe('.methodName', () => {
   });
 });
 ```
+
 #### Testing promises
 
 When testing Promises you should always make sure that the test is asynchronous and rejections are handled.
@@ -69,9 +70,9 @@ Your Promise chain should therefore end with a call of the `done` callback and `
 
 ```javascript
 // Good
-it('tests a promise', (done) => {
+it('tests a promise', done => {
   promise
-    .then((data) => {
+    .then(data => {
       expect(data).toBe(asExpected);
     })
     .then(done)
@@ -79,10 +80,10 @@ it('tests a promise', (done) => {
 });
 
 // Good
-it('tests a promise rejection', (done) => {
+it('tests a promise rejection', done => {
   promise
     .then(done.fail)
-    .catch((error) => {
+    .catch(error => {
       expect(error).toBe(expectedError);
     })
     .then(done)
@@ -91,48 +92,85 @@ it('tests a promise rejection', (done) => {
 
 // Bad (missing done callback)
 it('tests a promise', () => {
-  promise
-    .then((data) => {
-      expect(data).toBe(asExpected);
-    })
+  promise.then(data => {
+    expect(data).toBe(asExpected);
+  });
 });
 
 // Bad (missing catch)
-it('tests a promise', (done) => {
+it('tests a promise', done => {
   promise
-    .then((data) => {
+    .then(data => {
       expect(data).toBe(asExpected);
     })
-    .then(done)
+    .then(done);
 });
 
 // Bad (use done.fail in asynchronous tests)
-it('tests a promise', (done) => {
+it('tests a promise', done => {
   promise
-    .then((data) => {
+    .then(data => {
       expect(data).toBe(asExpected);
     })
     .then(done)
-    .catch(fail)
+    .catch(fail);
 });
 
 // Bad (missing catch)
-it('tests a promise rejection', (done) => {
+it('tests a promise rejection', done => {
   promise
-    .catch((error) => {
+    .catch(error => {
       expect(error).toBe(expectedError);
     })
-    .then(done)
+    .then(done);
 });
 ```
 
-#### Stubbing
+#### Stubbing and Mocking
+
+Jasmine provides useful helpers `spyOn`, `spyOnProperty`, `jasmine.createSpy`,
+and `jasmine.createSpyObject` to facilitate replacing methods with dummy
+placeholders, and recalling when they are called and the arguments that are
+passed to them. These tools should be used liberally, to test for expected
+behavior, to mock responses, and to block unwanted side effects (such as a
+method that would generate a network request or alter `window.location`). The
+documentation for these methods can be found in the [jasmine introduction page](https://jasmine.github.io/2.0/introduction.html#section-Spies).
+
+Sometimes you may need to spy on a method that is directly imported by another
+module. GitLab has a custom `spyOnDependency` method which utilizes
+[babel-plugin-rewire](https://github.com/speedskater/babel-plugin-rewire) to
+achieve this. It can be used like so:
+
+```javascript
+// my_module.js
+import { visitUrl } from '~/lib/utils/url_utility';
+
+export default function doSomething() {
+  visitUrl('/foo/bar');
+}
+
+// my_module_spec.js
+import doSomething from '~/my_module';
+
+describe('my_module', () => {
+  it('does something', () => {
+    const visitUrl = spyOnDependency(doSomething, 'visitUrl');
+
+    doSomething();
+    expect(visitUrl).toHaveBeenCalledWith('/foo/bar');
+  });
+});
+```
 
-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.
+Unlike `spyOn`, `spyOnDependency` expects its first parameter to be the default
+export of a module who's import you want to stub, rather than an object which
+contains a method you wish to stub (if the module does not have a default
+export, one is be generated by the babel plugin). The second parameter is the
+name of the import you wish to change. The result of the function is a Spy
+object which can be treated like any other jasmine spy object.
 
-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.
+Further documentation on the babel rewire pluign API can be found on
+[its repository Readme doc](https://github.com/speedskater/babel-plugin-rewire#babel-plugin-rewire).
 
 ### Vue.js unit tests
 
@@ -143,8 +181,8 @@ See this [section][vue-test].
 `rake karma` runs the frontend-only (JavaScript) tests.
 It consists of two subtasks:
 
-- `rake karma:fixtures` (re-)generates fixtures
-- `rake karma:tests` actually executes the tests
+* `rake karma:fixtures` (re-)generates fixtures
+* `rake karma:tests` actually executes the tests
 
 As long as the fixtures don't change, `rake karma:tests` (or `yarn karma`)
 is sufficient (and saves you some time).
@@ -152,19 +190,41 @@ is sufficient (and saves you some time).
 ### Live testing and focused testing
 
 While developing locally, it may be helpful to keep karma running so that you
-can get instant feedback on as you write tests and modify code.  To do this
-you can start karma with `npm run karma-start`.  It will compile the javascript
+can get instant feedback on as you write tests and modify code. To do this
+you can start karma with `yarn run karma-start`. It will compile the javascript
 assets and run a server at `http://localhost:9876/` where it will automatically
-run the tests on any browser which connects to it.  You can enter that url on
+run the tests on any browser which connects to it. You can enter that url on
 multiple browsers at once to have it run the tests on each in parallel.
 
 While karma is running, any changes you make will instantly trigger a recompile
 and retest of the entire test suite, so you can see instantly if you've broken
-a test with your changes.  You can use [jasmine focused][jasmine-focus] or
+a test with your changes. You can use [jasmine focused][jasmine-focus] or
 excluded tests (with `fdescribe` or `xdescribe`) to get karma to run only the
 tests you want while you're working on a specific feature, but make sure to
 remove these directives when you commit your code.
 
+It is also possible to only run karma on specific folders or files by filtering
+the run tests via the argument `--filter-spec` or short `-f`:
+
+```bash
+# Run all files
+yarn karma-start
+# Run specific spec files
+yarn karma-start --filter-spec profile/account/components/update_username_spec.js
+# Run specific spec folder
+yarn karma-start --filter-spec profile/account/components/
+# Run all specs which path contain vue_shared or vie
+yarn karma-start -f vue_shared -f vue_mr_widget
+```
+
+You can also use glob syntax to match files. Remember to put quotes around the
+glob otherwise your shell may split it into multiple arguments:
+
+```bash
+# Run all specs named `file_spec` within the IDE subdirectory
+yarn karma -f 'spec/javascripts/ide/**/file_spec.js'
+```
+
 ## RSpec feature integration tests
 
 Information on setting up and running RSpec integration tests with
@@ -176,19 +236,19 @@ Information on setting up and running RSpec integration tests with
 
 Similar errors will be thrown if you're using JavaScript features not yet
 supported by the PhantomJS test runner which is used for both Karma and RSpec
-tests.  We polyfill some JavaScript objects for older browsers, but some
+tests. We polyfill some JavaScript objects for older browsers, but some
 features are still unavailable:
 
-- Array.from
-- Array.first
-- Async functions
-- Generators
-- Array destructuring
-- For..Of
-- Symbol/Symbol.iterator
-- Spread
+* Array.from
+* Array.first
+* Async functions
+* Generators
+* Array destructuring
+* For..Of
+* Symbol/Symbol.iterator
+* Spread
 
-Until these are polyfilled appropriately, they should not be used.  Please
+Until these are polyfilled appropriately, they should not be used. Please
 update this list with additional unsupported features.
 
 ### RSpec errors due to JavaScript
@@ -220,34 +280,14 @@ describe "Admin::AbuseReports", :js do
 end
 ```
 
-### Spinach errors due to missing JavaScript
-
-NOTE: **Note:** Since we are discouraging the use of Spinach when writing new
-feature tests, you shouldn't ever need to use this.  This information is kept
-available for legacy purposes only.
-
-In Spinach, the JavaScript driver is enabled differently. In the `*.feature`
-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"
-```
-
 [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
-[RSpec]: https://github.com/rspec/rspec-rails#feature-specs
-[Capybara]: https://github.com/teamcapybara/capybara
-[Karma]: http://karma-runner.github.io/
-[Jasmine]: https://jasmine.github.io/
+[vue-test]: https://docs.gitlab.com/ce/development/fe_guide/vue.html#testing-vue-components
+[rspec]: https://github.com/rspec/rspec-rails#feature-specs
+[capybara]: https://github.com/teamcapybara/capybara
+[karma]: http://karma-runner.github.io/
+[jasmine]: https://jasmine.github.io/
 
 ---
 
diff --git a/doc/development/testing_guide/index.md b/doc/development/testing_guide/index.md
index 74d09eb91ff..0cd63a54b55 100644
--- a/doc/development/testing_guide/index.md
+++ b/doc/development/testing_guide/index.md
@@ -72,21 +72,6 @@ Everything you should know about how to run end-to-end tests using
 
 ---
 
-## Spinach (feature) tests
-
-GitLab [moved from Cucumber to Spinach](https://github.com/gitlabhq/gitlabhq/pull/1426)
-for its feature/integration tests in September 2012.
-
-As of March 2016, we are [trying to avoid adding new Spinach
-tests](https://gitlab.com/gitlab-org/gitlab-ce/issues/14121) going forward,
-opting for [RSpec feature](#features-integration) specs.
-
-Adding new Spinach scenarios is acceptable _only if_ the new scenario requires
-no more than one new `step` definition. If more than that is required, the
-test should be re-implemented using RSpec instead.
-
----
-
 [Return to Development documentation](../README.md)
 
 [^1]: /ci/yaml/README.html#dependencies
diff --git a/doc/development/testing_guide/testing_levels.md b/doc/development/testing_guide/testing_levels.md
index e86c1f5232a..07ced36f0c1 100644
--- a/doc/development/testing_guide/testing_levels.md
+++ b/doc/development/testing_guide/testing_levels.md
@@ -28,7 +28,7 @@ records should use stubs/doubles as much as possible.
 | `app/uploaders/` | `spec/uploaders/` | RSpec | |
 | `app/views/` | `spec/views/` | RSpec | |
 | `app/workers/` | `spec/workers/` | RSpec | |
-| `app/assets/javascripts/` | `spec/javascripts/` | Karma | More details in the [Frontent Testing guide](frontend_testing.md) section. |
+| `app/assets/javascripts/` | `spec/javascripts/` | Karma | More details in the [Frontend Testing guide](frontend_testing.md) section. |
 
 ## Integration tests
 
@@ -81,7 +81,6 @@ possible).
 | Tests path | Testing engine | Notes |
 | ---------- | -------------- | ----- |
 | `spec/features/` | [Capybara] + [RSpec] | If your spec has the `:js` metadata, the browser driver will be [Poltergeist], otherwise it's using [RackTest]. |
-| `features/` | Spinach | Spinach tests are deprecated, [you shouldn't add new Spinach tests](#spinach-feature-tests). |
 
 ### Consider **not** writing a system test!
 
diff --git a/doc/development/testing_guide/testing_rake_tasks.md b/doc/development/testing_guide/testing_rake_tasks.md
index 60163f1a230..db8ca87e9f8 100644
--- a/doc/development/testing_guide/testing_rake_tasks.md
+++ b/doc/development/testing_guide/testing_rake_tasks.md
@@ -9,7 +9,7 @@ At a minimum, requiring the Rake helper will redirect `stdout`, include the
 runtime task helpers, and include the `RakeHelpers` Spec support module.
 
 The `RakeHelpers` module exposes a `run_rake_task(<task>)` method to make
-executing tasks simple. See `spec/support/rake_helpers.rb` for all available
+executing tasks simple. See `spec/support/helpers/rake_helpers.rb` for all available
 methods.
 
 Example:
diff --git a/doc/development/utilities.md b/doc/development/utilities.md
index 8f9aff1a35f..0d074a3ef05 100644
--- a/doc/development/utilities.md
+++ b/doc/development/utilities.md
@@ -135,3 +135,44 @@ We developed a number of utilities to ease development.
 
     Find.new.clear_memoization(:result)
     ```
+
+## [`RequestCache`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/gitlab/cache/request_cache.rb)
+
+This module provides a simple way to cache values in RequestStore,
+and the cache key would be based on the class name, method name,
+optionally customized instance level values, optionally customized
+method level values, and optional method arguments.
+
+A simple example that only uses the instance level customised values:
+
+``` ruby
+class UserAccess
+  extend Gitlab::Cache::RequestCache
+
+  request_cache_key do
+    [user&.id, project&.id]
+  end
+
+  request_cache def can_push_to_branch?(ref)
+    # ...
+  end
+end
+```
+
+This way, the result of `can_push_to_branch?` would be cached in
+`RequestStore.store` based on the cache key. If `RequestStore` is not
+currently active, then it would be stored in a hash saved in an
+instance variable, so the cache logic would be the same.
+
+We can also set different strategies for different methods:
+
+``` ruby
+class Commit
+  extend Gitlab::Cache::RequestCache
+
+  def author
+    User.find_by_any_email(author_email.downcase)
+  end
+  request_cache(:author) { author_email.downcase }
+end
+```
diff --git a/doc/development/ux_guide/components.md b/doc/development/ux_guide/components.md
index 012c64be79f..4a3b3125f59 100644
--- a/doc/development/ux_guide/components.md
+++ b/doc/development/ux_guide/components.md
@@ -193,7 +193,7 @@ List with avatar, title and description using .content-list
 
 ![List with avatar](img/components-listwithavatar.png)
 
-List with hover effect .well-list
+List with hover effect .content-list
 
 ![List with hover effect](img/components-listwithhover.png)
 
@@ -219,7 +219,7 @@ Blocks are a way to group related information.
 
 #### Content blocks
 
-Content blocks (`.content-block`) are the basic grouping of content. They are commonly used in [lists](#lists), and are separated by a botton border.
+Content blocks (`.content-block`) are the basic grouping of content. They are commonly used in [lists](#lists), and are separated by a button border.
 
 ![Content block](img/components-contentblock.png)
 
@@ -281,7 +281,7 @@ Modals are only used for having a conversation and confirmation with the user. T
 
 | Modal with 2 actions | Modal with 3 actions | Special confirmation |
 | --------------------- | --------------------- | -------------------- |
-| ![two-actions](img/modals-general-confimation-dialog.png) | ![three-actions](img/modals-three-buttons.png) | ![spcial-confirmation](img/modals-special-confimation-dialog.png) |
+| ![two-actions](img/modals-general-confimation-dialog.png) | ![three-actions](img/modals-three-buttons.png) | ![special-confirmation](img/modals-special-confimation-dialog.png) |
 
 > TODO: Special case for modal.
 
diff --git a/doc/development/what_requires_downtime.md b/doc/development/what_requires_downtime.md
index 9d0c62ecc35..47396666879 100644
--- a/doc/development/what_requires_downtime.md
+++ b/doc/development/what_requires_downtime.md
@@ -195,22 +195,22 @@ end
 
 And that's it, we're done!
 
-## Changing Column Types For Large Tables
+## Changing The Schema For Large Tables
 
-While `change_column_type_concurrently` can be used for changing the type of a
-column without downtime it doesn't work very well for large tables. Because all
-of the work happens in sequence the migration can take a very long time to
-complete, preventing a deployment from proceeding.
-`change_column_type_concurrently` can also produce a lot of pressure on the
-database due to it rapidly updating many rows in sequence.
+While `change_column_type_concurrently` and `rename_column_concurrently` can be
+used for changing the schema of a table without downtime it doesn't work very
+well for large tables. Because all of the work happens in sequence the migration
+can take a very long time to complete, preventing a deployment from proceeding.
+They can also produce a lot of pressure on the database due to it rapidly
+updating many rows in sequence.
 
 To reduce database pressure you should instead use
-`change_column_type_using_background_migration` when migrating a column in a
-large table (e.g. `issues`). This method works similar to
-`change_column_type_concurrently` but uses background migration to spread the
-work / load over a longer time period, without slowing down deployments.
+`change_column_type_using_background_migration` or `rename_column_concurrently`
+when migrating a column in a large table (e.g. `issues`). These methods work
+similarly to the concurrent counterparts but uses background migration to spread
+the work / load over a longer time period, without slowing down deployments.
 
-Usage of this method is fairly simple:
+For example, to change the column type using a background migration:
 
 ```ruby
 class ExampleMigration < ActiveRecord::Migration
@@ -252,10 +252,66 @@ Keep in mind that the relation passed to
 `change_column_type_using_background_migration` _must_ include `EachBatch`,
 otherwise it will raise a `TypeError`.
 
+This migration then needs to be followed in a separate release (_not_ a patch
+release) by a cleanup migration, which should steal from the queue and handle
+any remaining rows. For example:
+
+```ruby
+class MigrateRemainingIssuesClosedAt < ActiveRecord::Migration
+  include Gitlab::Database::MigrationHelpers
+
+  DOWNTIME = false
+
+  disable_ddl_transaction!
+
+  class Issue < ActiveRecord::Base
+    self.table_name = 'issues'
+    include EachBatch
+  end
+
+  def up
+    Gitlab::BackgroundMigration.steal('CopyColumn')
+    Gitlab::BackgroundMigration.steal('CleanupConcurrentTypeChange')
+
+    migrate_remaining_rows if migrate_column_type?
+  end
+
+  def down
+    # Previous migrations already revert the changes made here.
+  end
+
+  def migrate_remaining_rows
+    Issue.where('closed_at_for_type_change IS NULL AND closed_at IS NOT NULL').each_batch do |batch|
+      batch.update_all('closed_at_for_type_change = closed_at')
+    end
+
+    cleanup_concurrent_column_type_change(:issues, :closed_at)
+  end
+
+  def migrate_column_type?
+    # Some environments may have already executed the previous version of this
+    # migration, thus we don't need to migrate those environments again.
+    column_for('issues', 'closed_at').type == :datetime # rubocop:disable Migration/Datetime
+  end
+end
+```
+
+The same applies to `rename_column_using_background_migration`:
+
+1. Create a migration using the helper, which will schedule background
+   migrations to spread the writes over a longer period of time.
+2. In the next monthly release, create a clean-up migration to steal from the
+   Sidekiq queues, migrate any missing rows, and cleanup the rename. This
+   migration should skip the steps after stealing from the Sidekiq queues if the
+   column has already been renamed.
+
+For more information, see [the documentation on cleaning up background
+migrations](background_migrations.md#cleaning-up).
+
 ## Adding Indexes
 
 Adding indexes is an expensive process that blocks INSERT and UPDATE queries for
-the duration. When using PostgreSQL one can work arounds this by using the
+the duration. When using PostgreSQL one can work around this by using the
 `CONCURRENTLY` option:
 
 ```sql
diff --git a/doc/development/writing_documentation.md b/doc/development/writing_documentation.md
index d6a13e7483a..038a4b1e6ea 100644
--- a/doc/development/writing_documentation.md
+++ b/doc/development/writing_documentation.md
@@ -1,541 +1,3 @@
-# GitLab Documentation guidelines
-
-  - **General Documentation**: written by the [developers responsible by creating features](#contributing-to-docs). Should be submitted in the same merge request containing code. Feature proposals (by GitLab contributors) should also be accompanied by its respective documentation. They can be later improved by PMs and Technical Writers.
-  - **[Technical Articles](#technical-articles)**: written by any [GitLab Team](https://about.gitlab.com/team/) member, GitLab contributors, or [Community Writers](https://about.gitlab.com/handbook/product/technical-writing/community-writers/).
-  - **Indexes per topic**: initially prepared by the Technical Writing Team, and kept up-to-date by developers and PMs in the same merge request containing code. They gather all resources for that topic in a single page (user and admin documentation, articles, and third-party docs).
-
-## Contributing to docs
-
-Whenever a feature is changed, updated, introduced, or deprecated, the merge
-request introducing these changes must be accompanied by the documentation
-(either updating existing ones or creating new ones). This is also valid when
-changes are introduced to the UI.
-
-The one responsible for writing the first piece of documentation is the developer who
-wrote the code. It's the job of the Product Manager to ensure all features are
-shipped with its docs, whether is a small or big change. At the pace GitLab evolves,
-this is the only way to keep the docs up-to-date. If you have any questions about it,
-ask a Technical Writer. Otherwise, when your content is ready, assign one of
-them to review it for you.
-
-We use the [monthly release blog post](https://about.gitlab.com/handbook/marketing/blog/release-posts/#monthly-releases) as a changelog checklist to ensure everything
-is documented.
-
-Whenever you submit a merge request for the documentation, use the documentation MR description template.
-
-Please check the [documentation workflow](https://about.gitlab.com/handbook/product/technical-writing/workflow/) before getting started.
-
-## Documentation structure
-
-- Overview and use cases: what it is, why it is necessary, why one would use it
-- Requirements: what do we need to get started
-- Tutorial: how to set it up, how to use it
-
-Always link a new document from its topic-related index, otherwise, it will
-not be included it in the documentation site search.
-
-_Note: to be extended._
-
-### Feature overview and use cases
-
-Every major feature (regardless if present in GitLab Community or Enterprise editions)
-should present, at the beginning of the document, two main sections: **overview** and
-**use cases**. Every GitLab EE-only feature should also contain these sections.
-
-**Overview**: as the name suggests, the goal here is to provide an overview of the feature.
-Describe what is it, what it does, why it is important/cool/nice-to-have,
-what problem it solves, and what you can do with this feature that you couldn't
-do before.
-
-**Use cases**: provide at least two, ideally three, use cases for every major feature.
-You should answer this question: what can you do with this feature/change? Use cases
-are examples of how this feauture or change can be used in real life.
-
-Examples:
-- CE and EE: [Issues](../user/project/issues/index.md#use-cases)
-- CE and EE: [Merge Requests](../user/project/merge_requests/index.md#overview)
-- EE-only: [Geo](https://docs.gitlab.com/ee/gitlab-geo/README.html#overview)
-- EE-only: [Jenkins integration](https://docs.gitlab.com/ee/integration/jenkins.md#overview)
-
-Note that if you don't have anything to add between the doc title (`<h1>`) and
-the header `## Overview`, you can omit the header, but keep the content of the
-overview there.
-
-> **Overview** and **use cases** are required to **every** Enterprise Edition feature,
-and for every **major** feature present in Community Edition.
-
-## Markdown and styles
-
-Currently GitLab docs use Redcarpet as [markdown](../user/markdown.md) engine, but there's an [open discussion](https://gitlab.com/gitlab-com/gitlab-docs/issues/50) for implementing Kramdown in the near future.
-
-All the docs follow the [documentation style guidelines](doc_styleguide.md).
-
-## Documentation directory structure
-
-The documentation is structured based on the GitLab UI structure itself,
-separated by [`user`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/user),
-[`administrator`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/administration), and [`contributor`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/development). 
-
-In order to have a [solid site structure](https://searchengineland.com/seo-benefits-developing-solid-site-structure-277456) for our documentation,
-all docs should be linked. Every new document should be cross-linked to its related documentation, and linked from its topic-related index, when existent.
-
-The directories `/workflow/`, `/gitlab-basics/`, `/university/`, and `/articles/` have
-been deprecated and the majority their docs have been moved to their correct location
-in small iterations. Please don't create new docs in these folders.
-
-### Location and naming documents
-
-The documentation hierarchy can be vastly improved by providing a better layout
-and organization of directories.
-
-Having a structured document layout, we will be able to have meaningful URLs
-like `docs.gitlab.com/user/project/merge_requests/index.html`. With this pattern,
-you can immediately tell that you are navigating a user related documentation
-and is about the project and its merge requests.
-
-Do not create summaries of similar types of content (e.g. an index of all articles, videos, etc.),
-rather organize content by its subject (e.g. everything related to CI goes together)
-and cross-link between any related content.
-
-The table below shows what kind of documentation goes where.
-
-| Directory | What belongs here |
-| --------- | -------------- |
-| `doc/user/` | User related documentation. Anything that can be done within the GitLab UI goes here including `/admin`. |
-| `doc/administration/`  | Documentation that requires the user to have access to the server where GitLab is installed. The admin settings that can be accessed via GitLab's interface go under `doc/user/admin_area/`. |
-| `doc/api/` | API related documentation. |
-| `doc/development/` | Documentation related to the development of GitLab. Any styleguides should go here. |
-| `doc/legal/` | Legal documents about contributing to GitLab. |
-| `doc/install/`| Probably the most visited directory, since `installation.md` is there. Ideally this should go under `doc/administration/`, but it's best to leave it as-is in order to avoid confusion (still debated though). |
-| `doc/update/` | Same with `doc/install/`. Should be under `administration/`, but this is a well known location, better leave as-is, at least for now. |
-| `doc/topics/` | Indexes per Topic (`doc/topics/topic-name/index.md`): all resources for that topic (user and admin documentation, articles, and third-party docs) |
-
 ---
-
-**General rules:**
-
-1. The correct naming and location of a new document, is a combination
-   of the relative URL of the document in question and the GitLab Map design
-   that is used for UX purposes ([source][graffle], [image][gitlab-map]).
-1. When creating a new document and it has more than one word in its name,
-   make sure to use underscores instead of spaces or dashes (`-`). For example,
-   a proper naming would be `import_projects_from_github.md`. The same rule
-   applies to images.
-1. Start a new directory with an `index.md` file.
-1. There are four main directories, `user`, `administration`, `api` and `development`.
-1. The `doc/user/` directory has five main subdirectories: `project/`, `group/`,
-   `profile/`, `dashboard/` and `admin_area/`.
-   1. `doc/user/project/` should contain all project related documentation.
-   1. `doc/user/group/` should contain all group related documentation.
-   1. `doc/user/profile/` should contain all profile related documentation.
-      Every page you would navigate under `/profile` should have its own document,
-      i.e. `account.md`, `applications.md`, `emails.md`, etc.
-   1. `doc/user/dashboard/` should contain all dashboard related documentation.
-   1. `doc/user/admin_area/` should contain all admin related documentation
-      describing what can be achieved by accessing GitLab's admin interface
-      (_not to be confused with `doc/administration` where server access is
-      required_).
-      1. Every category under `/admin/application_settings` should have its
-         own document located at `doc/user/admin_area/settings/`. For example,
-         the **Visibility and Access Controls** category should have a document
-         located at `doc/user/admin_area/settings/visibility_and_access_controls.md`.
-1. The `doc/topics/` directory holds topic-related technical content. Create
-   `doc/topics/topic-name/subtopic-name/index.md` when subtopics become necessary.
-   General user- and admin- related documentation, should be placed accordingly.
-
-If you are unsure where a document should live, you can ping `@axil` or `@marcia` in your
-merge request.
-
-### Changing document location
-
-Changing a document's location is not to be taken lightly. Remember that the
-documentation is available to all installations under `help/` and not only to
-GitLab.com or http://docs.gitlab.com. Make sure this is discussed with the
-Documentation team beforehand.
-
-If you indeed need to change a document's location, do NOT remove the old
-document, but rather replace all of its contents with a new line:
-
-```
-This document was moved to [another location](path/to/new_doc.md).
-```
-
-where `path/to/new_doc.md` is the relative path to the root directory `doc/`.
-
+redirect_to: 'documentation/index.md'
 ---
-
-For example, if you were to move `doc/workflow/lfs/lfs_administration.md` to
-`doc/administration/lfs.md`, then the steps would be:
-
-1. Copy `doc/workflow/lfs/lfs_administration.md` to `doc/administration/lfs.md`
-1. Replace the contents of `doc/workflow/lfs/lfs_administration.md` with:
-
-    ```
-    This document was moved to [another location](../../administration/lfs.md).
-    ```
-
-1. Find and replace any occurrences of the old location with the new one.
-   A quick way to find them is to use `git grep`. First go to the root directory
-   where you cloned the `gitlab-ce` repository and then do:
-
-    ```
-    git grep -n "workflow/lfs/lfs_administration"
-    git grep -n "lfs/lfs_administration"
-    ```
-
-NOTE: **Note:**
-If the document being moved has any Disqus comments on it, there are extra steps
-to follow documented just [below](#redirections-for-pages-with-disqus-comments).
-
-Things to note:
-
-- Since we also use inline documentation, except for the documentation itself,
-  the document might also be referenced in the views of GitLab (`app/`) which will
-  render when visiting `/help`, and sometimes in the testing suite (`spec/`).
-- The above `git grep` command will search recursively in the directory you run
-  it in for `workflow/lfs/lfs_administration` and `lfs/lfs_administration`
-  and will print the file and the line where this file is mentioned.
-  You may ask why the two greps. Since we use relative paths to link to
-  documentation, sometimes it might be useful to search a path deeper.
-- The `*.md` extension is not used when a document is linked to GitLab's
-  built-in help page, that's why we omit it in `git grep`.
-- Use the checklist on the documentation MR description template.
-
-### Redirections for pages with Disqus comments
-
-If the documentation page being relocated already has any Disqus comments,
-we need to preserve the Disqus thread.
-
-Disqus uses an identifier per page, and for docs.gitlab.com, the page identifier
-is configured to be the page URL. Therefore, when we change the document location,
-we need to preserve the old URL as the same Disqus identifier.
-
-To do that, add to the frontmatter the variable `redirect_from`,
-using the old URL as value. For example, let's say I moved the document
-available under `https://docs.gitlab.com/my-old-location/README.html` to a new location,
-`https://docs.gitlab.com/my-new-location/index.html`.
-
-Into the **new document** frontmatter add the following:
-
-```yaml
----
-redirect_from: 'https://docs.gitlab.com/my-old-location/README.html'
----
-```
-
-Note: it is necessary to include the file name in the `redirect_from` URL,
-even if it's `index.html` or `README.html`.
-
-## Testing
-
-We treat documentation as code, thus have implemented some testing.
-Currently, the following tests are in place:
-
-1. `docs lint`: Check that all internal (relative) links work correctly and
-   that all cURL examples in API docs use the full switches. It's recommended
-   to [check locally](#previewing-locally) before pushing to GitLab by executing the command
-   `bundle exec nanoc check internal_links` on your local
-   [`gitlab-docs`](https://gitlab.com/gitlab-com/gitlab-docs) directory.
-1. [`ee_compat_check`](https://docs.gitlab.com/ee/development/automatic_ce_ee_merge.html#avoiding-ce-gt-ee-merge-conflicts-beforehand) (runs on CE only):
-    When you submit a merge request to GitLab Community Edition (CE),
-    there is this additional job that runs against Enterprise Edition (EE)
-    and checks if your changes can apply cleanly to the EE codebase.
-    If that job fails, read the instructions in the job log for what to do next.
-    As CE is merged into EE once a day, it's important to avoid merge conflicts.
-    Submitting an EE-equivalent merge request cherry-picking all commits from CE to EE is
-    essential to avoid them.
-
-## Branch naming
-
-If your contribution contains **only** documentation changes, you can speed up
-the CI process by following some branch naming conventions. You have three
-choices:
-
-| Branch name | Valid example |
-| ----------- | ------------- |
-| Starting with `docs/` | `docs/update-api-issues`     |
-| Starting with `docs-` | `docs-update-api-issues`     |
-| Ending in `-docs`     | `123-update-api-issues-docs` |
-
-If your branch name matches any of the above, it will run only the docs
-tests. If it doesn't, the whole test suite will run (including docs).
-
-## Merge requests for GitLab documentation
-
-Before getting started, make sure you read the introductory section
-"[contributing to docs](#contributing-to-docs)" above and the
-[tech writing workflow](https://about.gitlab.com/handbook/product/technical-writing/workflow/)
-for GitLab Team members.
-
-- Use the current [merge request description template](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.gitlab/merge_request_templates/Documentation.md)
-- Use the correct [branch name](#branch-naming)
-- Label the MR `Documentation`
-- Assign the correct milestone (see note below)
-
-
-NOTE: **Note:**
-If the release version you want to add the documentation to has already been
-frozen or released, use the label `Pick into X.Y` to get it merged into
-the correct release. Avoid picking into a past release as much as you can, as
-it increases the work of the release managers.
-
-### Cherry-picking from CE to EE
-
-As we have the `master` branch of CE merged into EE once a day, it's common to
-run into merge conflicts. To avoid them, we [test for merge conflicts against EE](#testing)
-with the `ee-compat-check` job, and use the following method of creating equivalent
-branches for CE and EE.
-
-Follow this [method for cherry-picking from CE to EE](automatic_ce_ee_merge.md#cherry-picking-from-ce-to-ee), with a few adjustments:
-
-- Create the [CE branch](#branch-naming) starting with `docs-`,
-  e.g.: `git checkout -b docs-example`
-- Create the EE-equivalent branch ending with `-ee`, e.g.,
-  `git checkout -b docs-example-ee`
-- Once all the jobs are passing in CE and EE, and you've addressed the
-feedback from your own team, assign the CE MR to a technical writer for review
-- When both MRs are ready, the EE merge request will be merged first, and the
-CE-equivalent will be merged next.
-- Note that the review will occur only in the CE MR, as the EE MR
-contains the same commits as the CE MR.
-- If you have a few more changes that apply to the EE-version only, you can submit
-a couple more commits to the EE branch, but ask the reviewer to review the EE merge request
-additionally to the CE MR. If there are many EE-only changes though, start a new MR
-to EE only.
-
-## Previewing the changes live
-
-To preview your changes to documentation locally, please follow
-this [development guide](https://gitlab.com/gitlab-com/gitlab-docs/blob/master/README.md#development).
-
-If you want to preview the doc changes of your merge request live, you can use
-the manual `review-docs-deploy` job in your merge request. You will need at
-least Master permissions to be able to run it and is currently enabled for the
-following projects:
-
-- https://gitlab.com/gitlab-org/gitlab-ce
-- https://gitlab.com/gitlab-org/gitlab-ee
-
-NOTE: **Note:**
-You will need to push a branch to those repositories, it doesn't work for forks.
-
-TIP: **Tip:**
-If your branch contains only documentation changes, you can use
-[special branch names](#branch-naming) to avoid long running pipelines.
-
-In the mini pipeline graph, you should see an `>>` icon. Clicking on it will
-reveal the `review-docs-deploy` job. Hit the play button for the job to start.
-
-![Manual trigger a docs build](img/manual_build_docs.png)
-
-This job will:
-
-1. Create a new branch in the [gitlab-docs](https://gitlab.com/gitlab-com/gitlab-docs)
-   project named after the scheme: `preview-<branch-slug>`
-1. Trigger a cross project pipeline and build the docs site with your changes
-
-After a few minutes, the Review App will be deployed and you will be able to
-preview the changes. The docs URL can be found in two places:
-
-- In the merge request widget
-- In the output of the `review-docs-deploy` job, which also includes the
-  triggered pipeline so that you can investigate whether something went wrong
-
-In case the Review App URL returns 404, follow these steps to debug:
-
-1. **Did you follow the URL from the merge request widget?** If yes, then check if
-   the link is the same as the one in the job output. It can happen that if the
-   branch name slug is longer than 35 characters, it is automatically
-   truncated. That means that the merge request widget will not show the proper
-   URL due to a limitation of how `environment: url` works, but you can find the
-   real URL from the output of the `review-docs-deploy` job.
-1. **Did you follow the URL from the job output?** If yes, then it means that
-   either the site is not yet deployed or something went wrong with the remote
-   pipeline. Give it a few minutes and it should appear online, otherwise you
-   can check the status of the remote pipeline from the link in the job output.
-   If the pipeline failed or got stuck, drop a line in the `#docs` chat channel.
-
-TIP: **Tip:**
-Someone that has no merge rights to the CE/EE projects (think of forks from
-contributors) will not be able to run the manual job. In that case, you can
-ask someone from the GitLab team who has the permissions to do that for you.
-
-NOTE: **Note:**
-Make sure that you always delete the branch of the merge request you were
-working on. If you don't, the remote docs branch won't be removed either,
-and the server where the Review Apps are hosted will eventually be out of
-disk space.
-
-### Technical aspects
-
-If you want to know the hot details, here's what's really happening:
-
-1. You manually run the `review-docs-deploy` job in a CE/EE merge request.
-1. The job runs the [`scripts/trigger-build-docs`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/scripts/trigger-build-docs)
-   script with the `deploy` flag, which in turn:
-   1. Takes your branch name and applies the following:
-      - The slug of the branch name is used to avoid special characters since
-        ultimately this will be used by NGINX.
-      - The `preview-` prefix is added to avoid conflicts if there's a remote branch
-        with the same name that you created in the merge request.
-      - The final branch name is truncated to 42 characters to avoid filesystem
-        limitations with long branch names (> 63 chars).
-   1. The remote branch is then created if it doesn't exist (meaning you can
-      re-run the manual job as many times as you want and this step will be skipped).
-   1. A new cross-project pipeline is triggered in the docs project.
-   1. The preview URL is shown both at the job output and in the merge request
-      widget. You also get the link to the remote pipeline.
-1. In the docs project, the pipeline is created and it
-   [skips the test jobs](https://gitlab.com/gitlab-com/gitlab-docs/blob/8d5d5c750c602a835614b02f9db42ead1c4b2f5e/.gitlab-ci.yml#L50-55)
-   to lower the build time.
-1. Once the docs site is built, the HTML files are uploaded as artifacts.
-1. A specific Runner tied only to the docs project, runs the Review App job
-   that downloads the artifacts and uses `rsync` to transfer the files over
-   to a location where NGINX serves them.
-
-The following GitLab features are used among others:
-
-- [Manual actions](../ci/yaml/README.md#manual-actions)
-- [Multi project pipelines](https://docs.gitlab.com/ee/ci/multi_project_pipeline_graphs.html)
-- [Review Apps](../ci/review_apps/index.md)
-- [Artifacts](../ci/yaml/README.md#artifacts)
-- [Specific Runner](../ci/runners/README.md#locking-a-specific-runner-from-being-enabled-for-other-projects)
-
-## GitLab `/help`
-
-Every GitLab instance includes the documentation, which is available from `/help`
-(`http://my-instance.com/help`), e.g., <https://gitlab.com/help>.
-
-When you're building a new feature, you may need to link the documentation
-from GitLab, the application. This is normally done in files inside the
-`app/views/` directory with the help of the `help_page_path` helper method.
-
-In its simplest form, the HAML code to generate a link to the `/help` page is:
-
-```haml
-= link_to 'Help page', help_page_path('user/permissions')
-```
-
-The `help_page_path` contains the path to the document you want to link to with
-the following conventions:
-
-- it is relative to the `doc/` directory in the GitLab repository
-- the `.md` extension must be omitted
-- it must not end with a slash (`/`)
-
-Below are some special cases where should be used depending on the context.
-You can combine one or more of the following:
-
-1. **Linking to an anchor link.** Use `anchor` as part of the `help_page_path`
-   method:
-
-    ```haml
-    = link_to 'Help page', help_page_path('user/permissions', anchor: 'anchor-link')
-    ```
-
-1. **Opening links in a new tab.** This should be the default behavior:
-
-    ```haml
-    = link_to 'Help page', help_page_path('user/permissions'), target: '_blank'
-    ```
-
-1. **Linking to a circle icon.** Usually used in settings where a long
-   description cannot be used, like near checkboxes. You can basically use
-   any font awesome icon, but prefer the `question-circle`:
-
-    ```haml
-    = link_to icon('question-circle'), help_page_path('user/permissions')
-    ```
-
-1. **Using a button link.** Useful in places where text would be out of context
-   with the rest of the page layout:
-
-    ```haml
-    = link_to 'Help page', help_page_path('user/permissions'),  class: 'btn btn-info'
-    ```
-
-1. **Using links inline of some text.**
-
-    ```haml
-    Description to #{link_to 'Help page', help_page_path('user/permissions')}.
-    ```
-
-1. **Adding a period at the end of the sentence.** Useful when you don't want
-   the period to be part of the link:
-
-    ```haml
-    = succeed '.' do
-      Learn more in the
-      = link_to 'Help page', help_page_path('user/permissions')
-    ```
-
-## General Documentation vs Technical Articles
-
-### General documentation
-
-General documentation is categorized by _User_, _Admin_, and _Contributor_, and describe what that feature is, what it does, and its available settings.
-
-### Technical Articles
-
-Technical articles replace technical content that once lived in the [GitLab Blog](https://about.gitlab.com/blog/), where they got out-of-date and weren't easily found.
-
-They are topic-related documentation, written with an user-friendly approach and language, aiming to provide the community with guidance on specific processes to achieve certain objectives.
-
-A technical article guides users and/or admins to achieve certain objectives (within guides and tutorials), or provide an overview of that particular topic or feature (within technical overviews). It can also describe the use, implementation, or integration of third-party tools with GitLab.
-
-They should be placed in a new directory named `/article-title/index.md` under a topic-related folder, and their images should be placed in `/article-title/img/`. For example, a new article on GitLab Pages should be placed in `doc/user/project/pages/article-title/` and a new article on GitLab CI/CD should be placed in `doc/ci/examples/article-title/`.
-
-#### Types of Technical Articles
-
-- **User guides**: technical content to guide regular users from point A to point B
-- **Admin guides**: technical content to guide administrators of GitLab instances from point A to point B
-- **Technical Overviews**: technical content describing features, solutions, and third-party integrations
-- **Tutorials**: technical content provided step-by-step on how to do things, or how to reach very specific objectives
-
-#### Understanding guides, tutorials, and technical overviews
-
-Suppose there's a process to go from point A to point B in 5 steps: `(A) 1 > 2 > 3 > 4 > 5 (B)`.
-
-A **guide** can be understood as a description of certain processes to achieve a particular objective. A guide brings you from A to B describing the characteristics of that process, but not necessarily going over each step. It can mention, for example, steps 2 and 3, but does not necessarily explain how to accomplish them.
-
-- Live example: "[Static sites and GitLab Pages domains (Part 1)](../user/project/pages/getting_started_part_one.md) to [Creating and Tweaking GitLab CI/CD for GitLab Pages (Part 4)](../user/project/pages/getting_started_part_four.md)"
-
-A **tutorial** requires a clear **step-by-step** guidance to achieve a singular objective. It brings you from A to B, describing precisely all the necessary steps involved in that process, showing each of the 5 steps to go from A to B.
-It does not only describes steps 2 and 3, but also shows you how to accomplish them.
-
-- Live example (on the blog): [Hosting on GitLab.com with GitLab Pages](https://about.gitlab.com/2016/04/07/gitlab-pages-setup/)
-
-A **technical overview** is a description of what a certain feature is, and what it does, but does not walk
-through the process of how to use it systematically.
-
-- Live example (on the blog): [GitLab Workflow, an overview](https://about.gitlab.com/2016/10/25/gitlab-workflow-an-overview/)
-
-#### Special format
-
-Every **Technical Article** contains a frontmatter at the beginning of the doc
-with the following information:
-
-- **Type of article** (user guide, admin guide, technical overview, tutorial)
-- **Knowledge level** expected from the reader to be able to follow through (beginner, intermediate, advanced)
-- **Author's name** and **GitLab.com handle**
-- **Publication date** (ISO format YYYY-MM-DD)
-
-For example:
-
-
-```yaml
----
-author: John Doe
-author_gitlab: johnDoe
-level: beginner
-article_type: user guide
-date: 2017-02-01
----
-```
-
-#### Technical Articles - Writing Method
-
-Use the [writing method](https://about.gitlab.com/handbook/product/technical-writing/#writing-method) defined by the Technical Writing team.
-
-[gitlab-map]: https://gitlab.com/gitlab-org/gitlab-design/raw/master/production/resources/gitlab-map.png
-[graffle]: https://gitlab.com/gitlab-org/gitlab-design/blob/d8d39f4a87b90fb9ae89ca12dc565347b4900d5e/production/resources/gitlab-map.graffle