Merge branch 'master' into 'patch-28'

# Conflicts:
#   doc/development/i18n/proofreader.md

80 files changed, 2796 insertions, 2563 deletions

diff --git a/doc/development/README.md b/doc/development/README.md
index 94e604d125d..bcf57a223f5 100644
--- a/doc/development/README.md
+++ b/doc/development/README.md
@@ -7,8 +7,8 @@ description: 'Learn how to contribute to GitLab.'
 
 ## Get started!
 
-- Setup GitLab's development environment with [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/README.md)
-- [GitLab contributing guide](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/CONTRIBUTING.md)
+- Set up GitLab's development environment with [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/README.md)
+- [GitLab contributing guide](contributing/index.md)
 - [Architecture](architecture.md) of GitLab
 - [Rake tasks](rake_tasks.md) for development
 
@@ -23,13 +23,14 @@ description: 'Learn how to contribute to GitLab.'
 
 ## UX and frontend guides
 
-- [UX guide](ux_guide/index.md) for building GitLab with existing CSS styles and elements
+- [GitLab Design System](https://design.gitlab.com/) for building GitLab with existing CSS styles and elements
 - [Frontend guidelines](fe_guide/index.md)
 - [Emoji guide](fe_guide/emojis.md)
 
 ## Backend guides
 
 - [GitLab utilities](utilities.md)
+- [Logging](logging.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
@@ -50,6 +51,8 @@ description: 'Learn how to contribute to GitLab.'
 - [Permissions](permissions.md)
 - [Prometheus metrics](prometheus_metrics.md)
 - [Guidelines for reusing abstractions](reusing_abstractions.md)
+- [DeclarativePolicy framework](policies.md)
+- [Switching to Rails 5](switching_to_rails5.md)
 
 ## Performance guides
 
diff --git a/doc/development/adding_database_indexes.md b/doc/development/adding_database_indexes.md
index ea6f14da3b9..d1d2b8c4907 100644
--- a/doc/development/adding_database_indexes.md
+++ b/doc/development/adding_database_indexes.md
@@ -28,9 +28,9 @@ to filter data by. Instead one should ask themselves the following questions:
 
 1. Can I write my query in such a way that it re-uses as many existing indexes
    as possible?
-2. Is the data going to be large enough that using an index will actually be
+1. Is the data going to be large enough that using an index will actually be
    faster than just iterating over the rows in the table?
-3. Is the overhead of maintaining the index worth the reduction in query
+1. Is the overhead of maintaining the index worth the reduction in query
    timings?
 
 We'll explore every question in detail below.
@@ -62,7 +62,7 @@ In short:
 
 1. Try to write your query in such a way that it re-uses as many existing
    indexes as possible.
-2. Run the query using `EXPLAIN ANALYZE` and study the output to find the most
+1. Run the query using `EXPLAIN ANALYZE` and study the output to find the most
    ideal query.
 
 ## Data Size
diff --git a/doc/development/api_graphql_styleguide.md b/doc/development/api_graphql_styleguide.md
index 6c6e198a7c3..95722c027ba 100644
--- a/doc/development/api_graphql_styleguide.md
+++ b/doc/development/api_graphql_styleguide.md
@@ -379,7 +379,7 @@ let(:mutation) do
   )
 end
 
-it 'returns a successfull response' do
+it 'returns a successful response' do
    post_graphql_mutation(mutation, current_user: user)
 
    expect(response).to have_gitlab_http_status(:success)
diff --git a/doc/development/architecture.md b/doc/development/architecture.md
index 66d8a4f2f6e..e65c5f05505 100644
--- a/doc/development/architecture.md
+++ b/doc/development/architecture.md
@@ -10,39 +10,182 @@ For information, see the [GitLab Release Process](https://gitlab.com/gitlab-org/
 
 Both EE and CE require some add-on components called gitlab-shell and Gitaly. These components are available from the [gitlab-shell](https://gitlab.com/gitlab-org/gitlab-shell/tree/master) and [gitaly](https://gitlab.com/gitlab-org/gitaly/tree/master) repositories respectively. New versions are usually tags but staying on the master branch will give you the latest stable version. New releases are generally around the same time as GitLab CE releases with exception for informal security updates deemed critical.
 
-## Physical office analogy
+## GitLab Omnibus Component by Component
 
-You can imagine GitLab as a physical office.
+This document is designed to be consumed by systems adminstrators and GitLab Support Engineers who want to understand more about the internals of GitLab and how they work together.
 
-**The repositories** are the goods GitLab handles.
-They can be stored in a warehouse.
-This can be either a hard disk, or something more complex, such as a NFS filesystem;
+When deployed, GitLab should be considered the amalgamation of the below processes. When troubleshooting or debugging, be as specific as possible as to which component you are referencing. That should increase clarity and reduce confusion.
 
-**Nginx** acts like the front-desk.
-Users come to Nginx and request actions to be done by workers in the office;
+### GitLab Process Descriptions
 
-**The database** is a series of metal file cabinets with information on:
- - The goods in the warehouse (metadata, issues, merge requests etc);
- - The users coming to the front desk (permissions)
+As of this writing, a fresh GitLab 11.3.0 install will show the following processes with `gitlab-ctl status`:
 
-**Redis** is a communication board with “cubby holes” that can contain tasks for office workers;
+```
+run: alertmanager: (pid 30829) 14207s; run: log: (pid 13906) 2432044s
+run: gitaly: (pid 30771) 14210s; run: log: (pid 13843) 2432046s
+run: gitlab-monitor: (pid 30788) 14209s; run: log: (pid 13868) 2432045s
+run: gitlab-workhorse: (pid 30758) 14210s; run: log: (pid 13855) 2432046s
+run: logrotate: (pid 30246) 3407s; run: log: (pid 13825) 2432047s
+run: nginx: (pid 30849) 14207s; run: log: (pid 13856) 2432046s
+run: node-exporter: (pid 30929) 14206s; run: log: (pid 13877) 2432045s
+run: postgres-exporter: (pid 30935) 14206s; run: log: (pid 13931) 2432044s
+run: postgresql: (pid 13133) 2432214s; run: log: (pid 13848) 2432046s
+run: prometheus: (pid 30807) 14209s; run: log: (pid 13884) 2432045s
+run: redis: (pid 30560) 14274s; run: log: (pid 13807) 2432047s
+run: redis-exporter: (pid 30946) 14205s; run: log: (pid 13869) 2432045s
+run: sidekiq: (pid 30953) 14205s; run: log: (pid 13810) 2432047s
+run: unicorn: (pid 30960) 14204s; run: log: (pid 13809) 2432047s
+``` 
+
+### Layers
+
+GitLab can be considered to have two layers from a process perspective:
+
+- **Monitoring**: Anything from this layer is not required to deliver GitLab the application, but will allow administrators more insight into their infrastructure and what the service as a whole is doing.
+- **Core**: Any process that is vital for the delivery of GitLab as a platform. If any of these processes halt there will be a GitLab outage. For the Core layer, you can further divide into:
+  - **Processors**: These processes are responsible for actually performing operations and presenting the service.
+  - **Data**: These services store/expose structured data for the GitLab service.
+
+### alertmanager
+
+- Omnibus configuration options
+- Layer: Monitoring
+
+[Alert manager](https://prometheus.io/docs/alerting/alertmanager/) is a tool provided by prometheus that _"handles alerts sent by client applications such as the Prometheus server. It takes care of deduplicating, grouping, and routing them to the correct receiver integration such as email, PagerDuty, or OpsGenie. It also takes care of silencing and inhibition of alerts."_ You can read more in [issue gitlab-ce#45740](https://gitlab.com/gitlab-org/gitlab-ce/issues/45740) about what we will be alerting on. 
+
+### gitaly
+
+- [Omnibus configuration options](https://gitlab.com/gitlab-org/gitaly/tree/master/doc/configuration) 
+- Layer: Core Service (Data)
+
+Gitaly is a service designed by GitLab to remove our need for NFS for Git storage in distributed deployments of GitLab. (Think GitLab.com or High Availablity Deployments) As of 11.3.0, This service handles all Git level access in GitLab. You can read more about the project [in the project's readme](https://gitlab.com/gitlab-org/gitaly).
+
+### gitlab-monitor
+
+- Omnibus configuration options
+- Layer: Monitoring 
+
+GitLab Monitor is a process disigned in house that allows us to export metrics about GitLab application internals to prometheus. You can read more [in the project's readme](https://gitlab.com/gitlab-org/gitlab-monitor)
+
+### gitlab-workhorse
+
+- Omnibus configuration options
+- Layer: Core Service (Processor)
+
+[GitLab Workhorse](https://gitlab.com/gitlab-org/gitlab-workhorse) is a program designed at GitLab to help alieviate pressure from unicorn. You can read more about the [historical reasons for developing](https://about.gitlab.com/2016/04/12/a-brief-history-of-gitlab-workhorse/). It's designed to act as a smart reverse proxy to help speed up GitLab as a whole.
+
+### logrotate
+
+- [Omnibus configuration options](https://docs.gitlab.com/omnibus/settings/logs.html#logrotate)
+- Layer: Core Service
+
+GitLab is comprised of a large number of services that all log. We started bundling our own logrotate as of 7.4 to make sure we were logging responsibly. This is just a packaged version of the common opensource offering.
+
+### nginx
+
+- [Omnibus configuration options](https://docs.gitlab.com/omnibus/settings/nginx.html)
+- Layer: Core Service (Processor)
+
+Nginx as an ingress port for all HTTP requests and routes them to the approriate sub-systems within GitLab. We are bundling an unmodified version of the popular open source webserver.
+
+### node-exporter
+
+- [Omnibus configuration options](https://docs.gitlab.com/ee/administration/monitoring/prometheus/node_exporter.html)
+- Layer: Monitoring
+
+[Node Exporter](https://github.com/prometheus/node_exporter) is a Prometheus tool that gives us metrics on the underlying machine. (Think CPU/Disk/Load) It's just a packaged version of the common open source offering from the Prometheus project.
+
+### postgres-exporter
+
+- [Omnibus configuration options](https://docs.gitlab.com/ee/administration/monitoring/prometheus/postgres_exporter.html)
+- Layer: Monitoring
+
+[Postgres-exporter](https://github.com/wrouesnel/postgres_exporter) is the community provided Prometheus exporter that will deliver data about Postgres to prometheus for use in Grafana Dashboards. 
+
+### postgresql
+
+- [Omnibus configuration options](https://docs.gitlab.com/omnibus/settings/database.html)
+- Layer: Core Service (Data)
+
+GitLab packages the popular Database to provide storage for Application meta data and user information.  
+
+### prometheus
+
+- [Omnibus configuration options](https://docs.gitlab.com/ee/administration/monitoring/prometheus/)
+- Layer: Monitoring
+
+Prometheus is a time-series tool that helps GitLab administrators expose metrics about the individual processes used to provide GitLab the service.
+
+### redis
+
+- [Omnibus configuration options](https://docs.gitlab.com/omnibus/settings/redis.html)
+- Layer: Core Service (Data)
+
+Redis is packaged to provide a place to store: 
+
+- session data
+- temporary cache information
+- background job queues. 
+
+### redis-exporter
+
+- [Omnibus configuration options](https://docs.gitlab.com/ee/administration/monitoring/prometheus/redis_exporter.html)
+- Layer: Monitoring
+
+[Redis Exporter](https://github.com/oliver006/redis_exporter) is designed to give specific metrics about the Redis process to Prometheus so that we can graph these metrics in Graphana.
+
+### sidekiq
+
+- Omnibus configuration options
+- Layer: Core Service (Processor)
+
+Sidekiq is a Ruby background job processor that pulls jobs from the redis queue and processes them. Background jobs allow GitLab to provide a faster request/response cycle by moving work into the background.
+
+### unicorn
+
+- [Omnibus configuration options](https://docs.gitlab.com/omnibus/settings/unicorn.html)
+- Layer: Core Service (Processor)
+
+[Unicorn](https://bogomips.org/unicorn/) is a Ruby application server that is used to run the core Rails Application that provides the user facing features in GitLab. Often process output you will see this as `bundle` or `config.ru` depending on the GitLab version. 
+
+### Additional Processes
+
+### GitLab Pages
+
+TODO
+
+### Mattermost
+
+TODO
+
+## GitLab by Request Type
+
+GitLab provides two "interfaces" for end users to access the service:
+
+- Web HTTP Requests (Viewing the UI/API)
+- Git HTTP/SSH Requests (Pushing/Pulling Git Data)
+
+It's important to understand the distinction as some processes are used in both and others are exclusive to a specific request type.
+
+### GitLab Web HTTP Request Cycle
+
+When making a request to an HTTP Endpoint (Think `/users/sign_in`) the request will take the following path through the GitLab Service:
+
+- nginx - Acts as our first line reverse proxy
+- gitlab-workhorse - This determines if it needs to go to the Rails application or somewhere else to reduce load on unicorn.
+- unicorn - Since this is a web request, and it needs to access the application it will go to Unicorn.
+- Postgres/Gitaly/Redis - Depending on the type of request, it may hit these services to store or retreive data.
 
-**Sidekiq** is a worker that primarily handles sending out emails.
-It takes tasks from the Redis communication board;
 
-**A Unicorn worker** is a worker that handles quick/mundane tasks.
-They work with the communication board (Redis).
-Their job description:
- - check permissions by checking the user session stored in a Redis “cubby hole”;
- - make tasks for Sidekiq;
- - fetch stuff from the warehouse or move things around in there;
+### GitLab Git Request Cycle
 
-**GitLab-shell** is a third kind of worker that takes orders from a fax machine (SSH) instead of the front desk (HTTP).
-GitLab-shell communicates with Sidekiq via the “communication board” (Redis), and asks quick questions of the Unicorn workers either directly or via the front desk.
+Below we describe the different pathing that HTTP vs. SSH Git requests will take. There is some overlap with the Web Request Cycle but also some differences.
 
-**Gitaly** is a back desk that is specialized on reaching the disks to perform git operations efficiently and keep a copy of the result of costly operations. All git operations go through Gitaly.
+### Web Request (80/443)
+TODO
 
-**GitLab Enterprise Edition (the application)** is the collection of processes and business practices that the office is run by.
+### SSH Request (22)
+TODO
 
 ## System Layout
 
diff --git a/doc/development/automatic_ce_ee_merge.md b/doc/development/automatic_ce_ee_merge.md
index f6509b5c1dd..58e08d432cc 100644
--- a/doc/development/automatic_ce_ee_merge.md
+++ b/doc/development/automatic_ce_ee_merge.md
@@ -17,6 +17,9 @@ This merge is done automatically in a
 1. If all conflicts are resolved after your resolution is pushed, keep the merge
    request assigned to you: **you are now responsible for the merge request to be
    green**
+1. If you are the last person to resolve the conflicts, the pipeline is green,
+   and you have merge rights, merge the MR, but **do not** choose to squash.
+   Otherwise, assign the MR to someone that can merge.
 1. If you need any help, you can ping the current [release managers], or ask in
    the `#ce-to-ee` Slack channel
 
@@ -63,7 +66,7 @@ EE version of your CE merge request.
 For each commit (except on `master`), the `ee_compat_check` CI job tries to
 detect if the current branch's changes will conflict during the CE->EE merge.
 
-The job reports what files are conflicting and how to setup a merge request
+The job reports what files are conflicting and how to set up a merge request
 against EE.
 
 #### How the job works
diff --git a/doc/development/build_test_package.md b/doc/development/build_test_package.md
index 439d228baef..c5f6adfeaeb 100644
--- a/doc/development/build_test_package.md
+++ b/doc/development/build_test_package.md
@@ -4,12 +4,13 @@ While developing a new feature or modifying an existing one, it is helpful if an
 installable package (or a docker image) containing those changes is available
 for testing. For this very purpose, a manual job is provided in the GitLab CI/CD
 pipeline that can be used to trigger a pipeline in the omnibus-gitlab repository
-that will create
-1. A deb package for Ubuntu 16.04, available as a build artifact, and
-2. A docker image, which is pushed to [Omnibus GitLab's container 
-registry](https://gitlab.com/gitlab-org/omnibus-gitlab/container_registry)
-(images titled `gitlab-ce` and `gitlab-ee` respectively and image tag is the
-commit which triggered the pipeline).
+that will create:
+
+- A deb package for Ubuntu 16.04, available as a build artifact, and
+- A docker image, which is pushed to [Omnibus GitLab's container
+  registry](https://gitlab.com/gitlab-org/omnibus-gitlab/container_registry)
+  (images titled `gitlab-ce` and `gitlab-ee` respectively and image tag is the
+  commit which triggered the pipeline).
 
 When you push a commit to either the gitlab-ce or gitlab-ee project, the
 pipeline for that commit will have a `build-package` manual action you can
diff --git a/doc/development/changelog.md b/doc/development/changelog.md
index 9e0c81b3d60..cd0a1f46d27 100644
--- a/doc/development/changelog.md
+++ b/doc/development/changelog.md
@@ -110,7 +110,8 @@ At this point the script would ask you to select the category of the change (map
 4. New deprecation
 5. Feature removal
 6. Security fix
-7. Other
+7. Performance improvement
+8. Other
 ```
 
 The entry filename is based on the name of the current Git branch. If you run
@@ -132,15 +133,15 @@ If you're working on the GitLab EE repository, the entry will be added to
 
 ### Arguments
 
-| Argument            | Shorthand | Purpose                                                                                                    |
-| -----------------   | --------- | ---------------------------------------------------------------------------------------------------------- |
-| [`--amend`]         |           | Amend the previous commit                                                                                  |
-| [`--force`]         | `-f`      | Overwrite an existing entry                                                                                |
-| [`--merge-request`] | `-m`      | Set merge request ID                                                                                       |
-| [`--dry-run`]       | `-n`      | Don't actually write anything, just print                                                                  |
-| [`--git-username`]  | `-u`      | Use Git user.name configuration as the author                                                              |
-| [`--type`]          | `-t`      | The category of the change, valid options are: added, fixed, changed, deprecated, removed, security, other |
-| [`--help`]          | `-h`      | Print help message                                                                                         |
+| Argument            | Shorthand | Purpose                                                                                                                                 |
+| -----------------   | --------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| [`--amend`]         |           | Amend the previous commit                                                                                                               |
+| [`--force`]         | `-f`      | Overwrite an existing entry                                                                                                             |
+| [`--merge-request`] | `-m`      | Set merge request ID                                                                                                                    |
+| [`--dry-run`]       | `-n`      | Don't actually write anything, just print                                                                                               |
+| [`--git-username`]  | `-u`      | Use Git user.name configuration as the author                                                                                           |
+| [`--type`]          | `-t`      | The category of the change, valid options are: `added`, `fixed`, `changed`, `deprecated`, `removed`, `security`, `performance`, `other` |
+| [`--help`]          | `-h`      | Print help message                                                                                                                      |
 
 [`--amend`]: #-amend
 [`--force`]: #-force-or-f
diff --git a/doc/development/chaos_endpoints.md b/doc/development/chaos_endpoints.md
new file mode 100644
index 00000000000..403a5b21827
--- /dev/null
+++ b/doc/development/chaos_endpoints.md
@@ -0,0 +1,117 @@
+# Generating chaos in a test GitLab instance
+
+As [Werner Vogels](https://twitter.com/Werner), the CTO at Amazon Web Services, famously put it, **Everything fails, all the time**.
+
+As a developer, it's as important to consider the failure modes in which your software will operate as much as normal operation. Doing so can mean the difference between a minor hiccup leading to a scattering of `500` errors experienced by a tiny fraction of users and a full site outage that affects all users for an extended period.
+
+To paraphrase [Tolstoy](https://en.wikipedia.org/wiki/Anna_Karenina_principle), _all happy servers are alike, but all failing servers are failing in their own way_. Luckily, there are ways we can attempt to simulate these failure modes, and the chaos endpoints are tools for assisting in this process.
+
+Currently, there are four endpoints for simulating the following conditions:
+
+- Slow requests.
+- CPU-bound requests.
+- Memory leaks.
+- Unexpected process crashes.
+
+## Enabling chaos endpoints
+
+For obvious reasons, these endpoints are not enabled by default. They can be enabled by setting the `GITLAB_ENABLE_CHAOS_ENDPOINTS` environment variable to `1`.
+
+For example, if you're using the [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit) this can be done with the following command:
+
+```bash
+GITLAB_ENABLE_CHAOS_ENDPOINTS=1 gdk run
+```
+
+## Securing the chaos endpoints
+
+DANGER: **Danger:**
+It is highly recommended that you secure access to the chaos endpoints using a secret token. This is recommended when enabling these endpoints locally and essential when running in a staging or other shared environment. You should not enable them in production unless you absolutely know what you're doing.
+
+A secret token can be set through the `GITLAB_CHAOS_SECRET` environment variable. For example, when using the [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit) this can be done with the following command:
+
+```bash
+GITLAB_ENABLE_CHAOS_ENDPOINTS=1 GITLAB_CHAOS_SECRET=secret gdk run
+```
+
+Replace `secret` with your own secret token.
+
+## Invoking chaos
+
+Once you have enabled the chaos endpoints and restarted the application, you can start testing using the endpoints.
+
+## Memory leaks
+
+To simulate a memory leak in your application, use the `/-/chaos/leakmem` endpoint.
+
+NOTE: **Note:**
+The memory is not retained after the request finishes. Once the request has completed, the Ruby garbage collector will attempt to recover the memory.
+
+```
+GET /-/chaos/leakmem
+GET /-/chaos/leakmem?memory_mb=1024
+GET /-/chaos/leakmem?memory_mb=1024&duration_s=50
+```
+
+| Attribute    | Type    | Required | Description                                                                        |
+| ------------ | ------- | -------- | ---------------------------------------------------------------------------------- |
+| `memory_mb`  | integer | no       | How much memory, in MB, should be leaked. Defaults to 100MB.                       |
+| `duration_s` | integer | no       | Minimum duration, in seconds, that the memory should be retained. Defaults to 30s. |
+
+```bash
+curl http://localhost:3000/-/chaos/leakmem?memory_mb=1024&duration_s=10 --header 'X-Chaos-Secret: secret'
+```
+
+## CPU spin
+
+This endpoint attempts to fully utilise a single core, at 100%, for the given period.
+
+Depending on your rack server setup, your request may timeout after a predermined period (normally 60 seconds).
+If you're using Unicorn, this is done by killing the worker process.
+
+```
+GET /-/chaos/cpuspin
+GET /-/chaos/cpuspin?duration_s=50
+```
+
+| Attribute    | Type    | Required | Description                                                           |
+| ------------ | ------- | -------- | --------------------------------------------------------------------- |
+| `duration_s` | integer | no       | Duration, in seconds, that the core will be utilised. Defaults to 30s |
+
+```bash
+curl http://localhost:3000/-/chaos/cpuspin?duration_s=60 --header 'X-Chaos-Secret: secret'
+```
+
+## Sleep
+
+This endpoint is similar to the CPU Spin endpoint but simulates off-processor activity, such as network calls to backend services. It will sleep for a given duration.
+
+As with the CPU Spin endpoint, this may lead to your request timing out if duration exceeds the configured limit.
+
+```
+GET /-/chaos/sleep
+GET /-/chaos/sleep?duration_s=50
+```
+
+| Attribute    | Type    | Required | Description                                                            |
+| ------------ | ------- | -------- | ---------------------------------------------------------------------- |
+| `duration_s` | integer | no       | Duration, in seconds, that the request will sleep for. Defaults to 30s |
+
+```bash
+curl http://localhost:3000/-/chaos/sleep?duration_s=60 --header 'X-Chaos-Secret: secret'
+```
+
+## Kill
+
+This endpoint will simulate the unexpected death of a worker process using a `kill` signal.
+
+NOTE: **Note:**
+Since this endpoint uses the `KILL` signal, the worker is not given a chance to cleanup or shutdown.
+
+```
+GET /-/chaos/kill
+```
+
+```bash
+curl http://localhost:3000/-/chaos/kill --header 'X-Chaos-Secret: secret'
+```
diff --git a/doc/development/code_review.md b/doc/development/code_review.md
index edf0b6f46df..7788d155154 100644
--- a/doc/development/code_review.md
+++ b/doc/development/code_review.md
@@ -1,55 +1,153 @@
 # Code Review Guidelines
 
+This guide contains advice and best practices for performing code review, and
+having your code reviewed.
+
+All merge requests for GitLab CE and EE, whether written by a GitLab team member
+or a volunteer contributor, must go through a code review process to ensure the
+code is effective, understandable, maintainable, and secure.
+
 ## Getting your merge request reviewed, approved, and merged
 
-There are a few rules to get your merge request accepted:
+You are strongly encouraged to get your code **reviewed** by a
+[reviewer](https://about.gitlab.com/handbook/engineering/#reviewer) as soon as
+there is any code to review, to get a second opinion on the chosen solution and
+implementation, and an extra pair of eyes looking for bugs, logic problems, or
+uncovered edge cases. The reviewer can be from a different team, but it is
+recommended to pick someone who knows the domain well. You can read more about the
+importance of involving reviewer(s) in the section on the responsibility of the author below.
+
+If you need some guidance (e.g. it's your first merge request), feel free to ask
+one of the [Merge request coaches][team].
+
+If you need assistance with security scans or comments, feel free to include the 
+Security Team (`@gitlab-com/gl-security`) in the review.
+
+Depending on the areas your merge request touches, it must be **approved** by one
+or more [maintainers](https://about.gitlab.com/handbook/engineering/#maintainer):
+
+For approvals, we use the approval functionality found in the merge request
+widget. Reviewers can add their approval by [approving additionally](https://docs.gitlab.com/ee/user/project/merge_requests/merge_request_approvals.html#adding-or-removing-an-approval).
+
+Getting your merge request **merged** also requires a maintainer. If it requires
+more than one approval, the last maintainer to review and approve it will also merge it.
+
+### Approval guidelines
 
-1. Your merge request should only be **merged by a [maintainer][team]**.
-   1. If your merge request includes only backend changes [^1], it must be
-      **approved by a [backend maintainer][projects]**.
-   1. If your merge request includes only frontend changes [^1], it must be
-      **approved by a [frontend maintainer][projects]**.
-   1. If your merge request includes UX changes [^1], it must
-      be **approved by a [UX team member][team]**.
+As described in the section on the responsibility of the maintainer below, you
+are recommended to get your merge request approved and merged by maintainer(s)
+from teams other than your own.
+
+   1. If your merge request includes backend changes [^1], it must be
+      **approved by a [backend maintainer](https://about.gitlab.com/handbook/engineering/projects/#gitlab-ce_maintainers_backend)**.
+   1. If your merge request includes frontend changes [^1], it must be
+      **approved by a [frontend maintainer](https://about.gitlab.com/handbook/engineering/projects/#gitlab-ce_maintainers_frontend)**.
+   1. If your merge request includes UX changes [^1], it must be
+      **approved by a [UX team member][team]**.
    1. If your merge request includes adding a new JavaScript library [^1], it must be
       **approved by a [frontend lead][team]**.
    1. If your merge request includes adding a new UI/UX paradigm [^1], it must be
       **approved by a [UX lead][team]**.
-   1. If your merge request includes frontend and backend changes [^1], it must
-      be **approved by a [frontend and a backend maintainer][projects]**.
-   1. If your merge request includes UX and frontend changes [^1], it must
-      be **approved by a [UX team member and a frontend maintainer][team]**.
-   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 [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. It is recommended that you assign a maintainer that is from a different team than your own.
-      This ensures that all code across GitLab is consistent and can be easily understood by all contributors.
-      
-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).
+   1. If your merge request includes a new dependency or a filesystem change, it must be
+      **approved by a [Distribution team member][team]**. See how to work with the [Distribution team](https://about.gitlab.com/handbook/engineering/dev-backend/distribution/) for more details.
 
-## Best practices
+#### Security requirements
 
-This guide contains advice and best practices for performing code review, and
-having your code reviewed.
+   1. If your merge request is processing, storing, or transferring any kind of [RED or ORANGE data](https://docs.google.com/document/d/15eNKGA3zyZazsJMldqTBFbYMnVUSQSpU14lo22JMZQY/edit) (this is a confidential document), it must be
+      **approved by a [Security Engineer][team]**.
+   1. If your merge request involves implementing, utilizing, or is otherwise related to any type of authentication, authorization, or session handling mechanism, it must be
+      **approved by a [Security Engineer][team]**.
+   1. If your merge request has a goal which requires a cryptographic function such as: confidentiality, integrity, authentication, or non-repudiation, it must be
+      **approved by a [Security Engineer][team]**.
 
-All merge requests for GitLab CE and EE, whether written by a GitLab team member
-or a volunteer contributor, must go through a code review process to ensure the
-code is effective, understandable, and maintainable.
+### The responsibility of the merge request author
+
+The responsibility to find the best solution and implement it lies with the
+merge request author.
+
+Before assigning a merge request to a maintainer for approval and merge, they
+should be confident that it actually solves the problem it was meant to solve,
+that it does so in the most appropriate way, that it satisfies all requirements,
+and that there are no remaining bugs, logical problems, uncovered edge cases,
+or known vulnerabilities. The merge request should also have a completed task
+list in its description and a passing CI pipeline to avoid unnecessary back and
+forth.
+
+To reach the required level of confidence in their solution, an author is expected
+to involve other people in the investigation and implementation processes as
+appropriate.
+
+They are encouraged to reach out to domain experts to discuss different solutions
+or get an implementation reviewed, to product managers and UX designers to clear
+up confusion or verify that the end result matches what they had in mind, to
+database specialists to get input on the data model or specific queries, or to
+any other developer to get an in-depth review of the solution.
+
+If an author is unsure if a merge request needs a domain expert's opinion, that's
+usually a pretty good sign that it does, since without it the required level of
+confidence in their solution will not have been reached.
 
-Any developer can, and is encouraged to, perform code review on merge requests
-of colleagues and contributors. However, the final decision to accept a merge
-request is up to one the project's maintainers, denoted on the
-[engineering projects][projects].
+Before the review, the author is requested to submit comments on the merge
+request diff alerting the reviewer to anything important as well as for anything
+that demands further explanation or attention.  Examples of content that may
+warrant a comment could be:
+
+- The addition of a linting rule (Rubocop, JS etc)
+- The addition of a library (Ruby gem, JS lib etc)
+- Where not obvious, a link to the parent class or method
+- Any benchmarking performed to complement the change
+- Potentially insecure code
+
+Do not add these comments directly to the source code, unless the
+reviewer requires you to do so.
+
+This
+[saves reviewers time and helps authors catch mistakes earlier](https://www.ibm.com/developerworks/rational/library/11-proven-practices-for-peer-review/index.html#__RefHeading__97_174136755).
+
+### The responsibility of the maintainer
+
+Maintainers are responsible for the overall health, quality, and consistency of
+the GitLab codebase, across domains and product areas.
+
+Consequently, their reviews will focus primarily on things like overall
+architecture, code organization, separation of concerns, tests, DRYness,
+consistency, and readability.
+
+Since a maintainer's job only depends on their knowledge of the overall GitLab
+codebase, and not that of any specific domain, they can review, approve and merge
+merge requests from any team and in any product area.
+
+In fact, authors are encouraged to get their merge requests merged by maintainers
+from teams other than their own, to ensure that all code across GitLab is consistent
+and can be easily understood by all contributors, from both inside and outside the
+company, without requiring team-specific expertise.
+
+Maintainers will do their best to also review the specifics of the chosen solution
+before merging, but as they are not necessarily domain experts, they may be poorly
+placed to do so without an unreasonable investment of time. In those cases, they
+will defer to the judgment of the author and earlier reviewers and involved domain
+experts, in favor of focusing on their primary responsibilities.
+
+If a developer who happens to also be a maintainer was involved in a merge request
+as a domain expert and/or reviewer, it is recommended that they are not also picked
+as the maintainer to ultimately approve and merge it.
+
+Maintainers should check before merging if the merge request is approved by the
+required approvers.
+
+Maintainers must check before merging if the merge request is introducing new
+vulnerabilities, by inspecting the list in the Merge Request [Security
+Widget](https://docs.gitlab.com/ee/user/project/merge_requests/#security-reports-ultimate).
+When in doubt, a [Security Engineer][team] can be involved. The list of detected 
+vulnerabilities must be either empty or containing:
+
+- dismissed vulnerabilities in case of false positives
+- vulnerabilities converted to issues
+
+Maintainers should **never** dismiss vulnerabilities to "empty" the list,
+without duly verifying them.
+
+## Best practices
 
 ### Everyone
 
@@ -97,6 +195,20 @@ first time.
   branch. Do not squash until the branch is ready to merge. Reviewers should be
   able to read individual updates based on their earlier feedback.
 
+### Assigning a merge request for a review
+
+If you want to have your merge request reviewed, you can assign it to any reviewer. The list of reviewers can be found on [Engineering projects](https://about.gitlab.com/handbook/engineering/projects/) page.
+
+You can also use `ready for review` label. That means that your merge request is ready to be reviewed and any reviewer can pick it. It is recommended to use that label only if there isn't time pressure and make sure the merge request is assigned to a reviewer.
+
+When your merge request was reviewed and can be passed to a maintainer you can either pick a specific maintainer or use a label `ready for merge`.
+
+It is responsibility of the author of a merge request that the merge request is reviewed. If it stays in `ready for review` state too long it is recommended to assign it to a specific reviewer.
+
+### List of merge requests ready for review
+
+Developers who have capacity can regularly check the list of [merge requests to review](https://gitlab.com/groups/gitlab-org/-/merge_requests?scope=all&utf8=%E2%9C%93&state=opened&label_name%5B%5D=ready%20for%20review) and assign any merge request they want to review.
+
 ### Reviewing code
 
 Understand why the change is necessary (fixes a bug, improves the user
@@ -121,6 +233,9 @@ experience, refactors the existing code). Then:
   subsequent revisions for anything that would be spotted after that.
 - Consider using the [Squash and
   merge][squash-and-merge] feature when the merge request has a lot of commits.
+  When merging code a maintainer should only use the squash feature if the
+  author has already set this option or if the merge request clearly contains a
+  messy commit history that is intended to be squashed.
 
 [squash-and-merge]: https://docs.gitlab.com/ee/user/project/merge_requests/squash_and_merge.html#squash-and-merge
 
@@ -162,41 +277,41 @@ Enterprise Edition instance. This has some implications:
 1. **Query changes** should be tested to ensure that they don't result in worse
    performance at the scale of GitLab.com:
    1. Generating large quantities of data locally can help.
-   2. Asking for query plans from GitLab.com is the most reliable way to validate
+   1. Asking for query plans from GitLab.com is the most reliable way to validate
       these.
-2. **Database migrations** must be:
+1. **Database migrations** must be:
    1. Reversible.
-   2. Performant at the scale of GitLab.com - ask a maintainer to test the
+   1. Performant at the scale of GitLab.com - ask a maintainer to test the
       migration on the staging environment if you aren't sure.
-   3. Categorised correctly:
+   1. Categorised correctly:
       - Regular migrations run before the new code is running on the instance.
       - [Post-deployment migrations](post_deployment_migrations.md) run _after_
         the new code is deployed, when the instance is configured to do that.
       - [Background migrations](background_migrations.md) run in Sidekiq, and
         should only be done for migrations that would take an extreme amount of
         time at GitLab.com scale.
-3. **Sidekiq workers**
+1. **Sidekiq workers**
    [cannot change in a backwards-incompatible way](sidekiq_style_guide.md#removing-or-renaming-queues):
    1. Sidekiq queues are not drained before a deploy happens, so there will be
       workers in the queue from the previous version of GitLab.
-   2. If you need to change a method signature, try to do so across two releases,
+   1. If you need to change a method signature, try to do so across two releases,
       and accept both the old and new arguments in the first of those.
-   3. Similarly, if you need to remove a worker, stop it from being scheduled in
+   1. Similarly, if you need to remove a worker, stop it from being scheduled in
       one release, then remove it in the next. This will allow existing jobs to
       execute.
-   4. Don't forget, not every instance will upgrade to every intermediate version
+   1. Don't forget, not every instance will upgrade to every intermediate version
       (some people may go from X.1.0 to X.10.0, or even try bigger upgrades!), so
       try to be liberal in accepting the old format if it is cheap to do so.
-4. **Cached values** may persist across releases. If you are changing the type a
+1. **Cached values** may persist across releases. If you are changing the type a
    cached value returns (say, from a string or nil to an array), change the
    cache key at the same time.
-5. **Settings** should be added as a
+1. **Settings** should be added as a
    [last resort](https://about.gitlab.com/handbook/product/#convention-over-configuration).
    If you're adding a new setting in `gitlab.yml`:
    1. Try to avoid that, and add to `ApplicationSetting` instead.
-   2. Ensure that it is also
+   1. Ensure that it is also
       [added to Omnibus](https://docs.gitlab.com/omnibus/settings/gitlab.yml.html#adding-a-new-setting-to-gitlab-yml).
-6. **Filesystem access** can be slow, so try to avoid
+1. **Filesystem access** can be slow, so try to avoid
    [shared files](shared_files.md) when an alternative solution is available.
 
 ### Credits
diff --git a/doc/development/contributing/community_roles.md b/doc/development/contributing/community_roles.md
new file mode 100644
index 00000000000..b9c369286d2
--- /dev/null
+++ b/doc/development/contributing/community_roles.md
@@ -0,0 +1,16 @@
+### Community members & roles
+
+GitLab community members and their privileges/responsibilities.
+
+| Roles | Responsibilities | Requirements |
+|-------|------------------|--------------|
+| Maintainer | Accepts merge requests on several GitLab projects | Added to the [team page](https://about.gitlab.com/team/). An expert on code reviews and knows the product/code base |
+| Reviewer | Performs code reviews on MRs | Added to the [team page](https://about.gitlab.com/team/) |
+| Developer |Has access to GitLab internal infrastructure & issues (e.g. HR-related) | GitLab employee or a Core Team member (with an NDA) |
+| Contributor | Can make contributions to all GitLab public projects | Have a GitLab.com account |
+
+[List of current reviewers/maintainers](https://about.gitlab.com/handbook/engineering/projects/#gitlab-ce).
+
+---
+
+[Return to Contributing documentation](index.md)
diff --git a/doc/development/contributing/design.md b/doc/development/contributing/design.md
index 45fe8c26591..79750878aac 100644
--- a/doc/development/contributing/design.md
+++ b/doc/development/contributing/design.md
@@ -1,13 +1,4 @@
-<!-- START doctoc generated TOC please keep comment here to allow auto update -->
-<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
-**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
-
-- [Implement design & UI elements](#implement-design--ui-elements)
-- [Style guides](#style-guides)
-
-<!-- END doctoc generated TOC please keep comment here to allow auto update -->
-
-## Implement design & UI elements
+# Implement design & UI elements
 
 For guidance on UX implementation at GitLab, please refer to our [Design System](https://design.gitlab.com/).
 
@@ -22,7 +13,10 @@ There is a special type label called ~"product discovery". It represents a disco
 
 ~"product discovery" issues are like any other issue and should contain a milestone label, ~"Deliverable" or ~"Stretch", when scheduled in the current milestone.
 
-The initial issue should be about the problem we are solving. If a separate [product discovery issue](#product-discovery-issues) is needed for additional research and design work, it will be created by a PM or UX person. Assign the ~UX, ~"product discovery" and ~"Deliverable" labels, add a milestone and use a title that makes it clear that the scheduled issue is product discovery
+The initial issue should be about the problem we are solving. If a separate [product discovery issue](https://about.gitlab.com/handbook/engineering/ux/ux-department-workflow/#how-we-use-labels)
+is needed for additional research and design work, it will be created by a PM or UX person.
+Assign the ~UX, ~"product discovery" and ~"Deliverable" labels, add a milestone and
+use a title that makes it clear that the scheduled issue is product discovery
 (e.g. `Product discovery for XYZ`).
 
 In order to complete a product discovery issue in a release, you must complete the following:
@@ -32,34 +26,6 @@ In order to complete a product discovery issue in a release, you must complete t
 1. Copy the design to the description of the delivery issue for which the product discovery issue was created. Do not simply refer to the product discovery issue as a separate source of truth.
 1. In some cases, a product discovery issue also identifies future enhancements that will not go into the issue that originated the product discovery issue. For these items, create new issues containing the designs to ensure they are not lost. Put the issues in the backlog if they are agreed upon as good ideas. Otherwise leave them for triage.
 
-## Style guides
-
-1.  [Ruby](https://github.com/bbatsov/ruby-style-guide).
-    Important sections include [Source Code Layout][rss-source] and
-    [Naming][rss-naming]. Use:
-    - multi-line method chaining style **Option A**: dot `.` on the second line
-    - string literal quoting style **Option A**: single quoted by default
-1.  [Rails](https://github.com/bbatsov/rails-style-guide)
-1.  [Newlines styleguide][newlines-styleguide]
-1.  [Testing][testing]
-1.  [JavaScript styleguide][js-styleguide]
-1.  [SCSS styleguide][scss-styleguide]
-1.  [Shell commands](../shell_commands.md) created by GitLab
-    contributors to enhance security
-1.  [Database Migrations](../migration_style_guide.md)
-1.  [Markdown](http://www.cirosantilli.com/markdown-styleguide)
-1.  [Documentation styleguide](https://docs.gitlab.com/ee/development/documentation/styleguide.html)
-1.  Interface text should be written subjectively instead of objectively. It
-    should be the GitLab core team addressing a person. It should be written in
-    present time and never use past tense (has been/was). For example instead
-    of _prohibited this user from being saved due to the following errors:_ the
-    text should be _sorry, we could not create your account because:_
-1.  Code should be written in [US English][us-english]
-
-This is also the style used by linting tools such as
-[RuboCop](https://github.com/bbatsov/rubocop),
-[PullReview](https://www.pullreview.com/) and [Hound CI](https://houndci.com).
-
 ---
 
 [Return to Contributing documentation](index.md)
diff --git a/doc/development/contributing/index.md b/doc/development/contributing/index.md
index eac7cb44c40..9da4c66933c 100644
--- a/doc/development/contributing/index.md
+++ b/doc/development/contributing/index.md
@@ -1,59 +1,26 @@
-<!-- START doctoc generated TOC please keep comment here to allow auto update -->
-<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
-**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
-
-- [Contribute to GitLab](#contribute-to-gitlab)
-- [Security vulnerability disclosure](#security-vulnerability-disclosure)
-- [Code of conduct](#code-of-conduct)
-- [Closing policy for issues and merge requests](#closing-policy-for-issues-and-merge-requests)
-- [Helping others](#helping-others)
-- [I want to contribute!](#i-want-to-contribute)
-- [Contribution Flow](#contribution-flow)
-- [Workflow labels](#workflow-labels)
-  - [Type labels](#type-labels)
-  - [Subject labels](#subject-labels)
-  - [Team labels](#team-labels)
-  - [Milestone labels](#milestone-labels)
-  - [Bug Priority labels](#bug-priority-labels)
-  - [Bug Severity labels](#bug-severity-labels)
-     - [Severity impact guidance](#severity-impact-guidance)
-  - [Label for community contributors](#label-for-community-contributors)
-- [Implement design & UI elements](#implement-design--ui-elements)
-- [Issue tracker](#issue-tracker)
-  - [Issue triaging](#issue-triaging)
-  - [Feature proposals](#feature-proposals)
-  - [Issue tracker guidelines](#issue-tracker-guidelines)
-  - [Issue weight](#issue-weight)
-  - [Regression issues](#regression-issues)
-  - [Technical and UX debt](#technical-and-ux-debt)
-  - [Stewardship](#stewardship)
-- [Merge requests](#merge-requests)
-  - [Merge request guidelines](#merge-request-guidelines)
-  - [Contribution acceptance criteria](#contribution-acceptance-criteria)
-- [Definition of done](#definition-of-done)
-- [Style guides](#style-guides)
-
-<!-- END doctoc generated TOC please keep comment here to allow auto update -->
-
-## Contribute to GitLab
-
-For a first-time step-by-step guide to the contribution process, see
-["Contributing to GitLab"](https://about.gitlab.com/contributing/).
+# Contribute to GitLab
 
 Thank you for your interest in contributing to GitLab. This guide details how
-to contribute to GitLab in a way that is efficient for everyone.
+to contribute to GitLab in a way that is easy for everyone.
+
+We want to create a welcoming environment for everyone who is interested in contributing. Please visit our [Code of Conduct page](https://about.gitlab.com/contributing/code-of-conduct) to learn more about our committment to an open and welcoming environment.
+
+For a first-time step-by-step guide to the contribution process, please see
+["Contributing to GitLab"](https://about.gitlab.com/contributing/).
 
-Looking for something to work on? Look for issues with the label [Accepting Merge Requests](#i-want-to-contribute).
+Looking for something to work on? Look for issues with the label [`Accepting merge requests`](#i-want-to-contribute).
 
-GitLab comes into two flavors, GitLab Community Edition (CE) our free and open
+GitLab comes in two flavors, GitLab Community Edition (CE) our free and open
 source edition, and GitLab Enterprise Edition (EE) which is our commercial
 edition. Throughout this guide you will see references to CE and EE for
 abbreviation.
 
-If you have read this guide and want to know how the GitLab [core team]
+To get an overview of GitLab community membership including those that would be reviewing or merging your contributions, please visit [the community roles page](community_roles.md).
+
+If you want to know how the GitLab [core team]
 operates please see [the GitLab contributing process](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/PROCESS.md).
 
-- [GitLab Inc engineers should refer to the engineering workflow document](https://about.gitlab.com/handbook/engineering/workflow/)
+[GitLab Inc engineers should refer to the engineering workflow document](https://about.gitlab.com/handbook/engineering/workflow/)
 
 ## Security vulnerability disclosure
 
@@ -65,33 +32,8 @@ vulnerabilities.
 
 ## Code of conduct
 
-As contributors and maintainers of this project, we pledge to respect all
-people who contribute through reporting issues, posting feature requests,
-updating documentation, submitting pull requests or patches, and other
-activities.
-
-We are committed to making participation in this project a harassment-free
-experience for everyone, regardless of level of experience, gender, gender
-identity and expression, sexual orientation, disability, personal appearance,
-body size, race, ethnicity, age, or religion.
-
-Examples of unacceptable behavior by participants include the use of sexual
-language or imagery, derogatory comments or personal attacks, trolling, public
-or private harassment, insults, or other unprofessional conduct.
-
-Project maintainers have the right and responsibility to remove, edit, or
-reject comments, commits, code, wiki edits, issues, and other contributions
-that are not aligned to this Code of Conduct. Project maintainers who do not
-follow the Code of Conduct may be removed from the project team.
-
-This code of conduct applies both within project spaces and in public spaces
-when an individual is representing the project or its community.
-
-Instances of abusive, harassing, or otherwise unacceptable behavior can be
-reported by emailing `contact@gitlab.com`.
-
-This Code of Conduct is adapted from the [Contributor Covenant][contributor-covenant], version 1.1.0,
-available at [http://contributor-covenant.org/version/1/1/0/](http://contributor-covenant.org/version/1/1/0/).
+Our code of conduct can be found on the
+["Contributing to GitLab"](https://about.gitlab.com/contributing/) page.
 
 ## Closing policy for issues and merge requests
 
@@ -124,10 +66,10 @@ the remaining issues on the GitHub issue tracker.
 
 ## I want to contribute!
 
-If you want to contribute to GitLab [issues with the label `Accepting Merge Requests` and small weight][accepting-mrs-weight]
-is a great place to start. Issues with a lower weight (1 or 2) are deemed
-suitable for beginners. These issues will be of reasonable size and challenge,
-for anyone to start contributing to GitLab. If you have any questions or need help visit [Getting Help](https://about.gitlab.com/getting-help/#discussion) to
+If you want to contribute to GitLab,
+[issues with the `Accepting merge requests` label](issue_workflow.md#label-for-community-contributors)
+are a great place to start.
+If you have any questions or need help visit [Getting Help](https://about.gitlab.com/getting-help/#discussion) to
 learn how to communicate with GitLab. If you're looking for a Gitter or Slack channel
 please consider we favor
 [asynchronous communication](https://about.gitlab.com/handbook/communication/#internal-communication) over real time communication. Thanks for your contribution!
@@ -154,93 +96,38 @@ When your code contains more than 500 changes, any major breaking changes, or an
 
 This [documentation](issue_workflow.md) outlines the current workflow labels.
 
-### Type labels
-
-This [documentation](issue_workflow.md) outlines the current type labels.
-
-### Subject labels
-
-This [documentation](issue_workflow.md) outlines the current subject labels.
-
-### Team labels
-
-This [documentation](issue_workflow.md) outlines the current team labels.
-
-### Milestone labels
-
-This [documentation](issue_workflow.md) outlines the current milestone labels.
-
-### Bug Priority labels
-
-This [documentation](issue_workflow.md) outlines the current bug priority  labels.
-
-### Bug Severity labels
-
-This [documentation](issue_workflow.md) outlines the current severity labels.
-
-#### Severity impact guidance
-
-This [documentation](issue_workflow.md) outlines the current severity impact guidance.
-
-### Label for community contributors
-
-This [documentation](issue_workflow.md) outlines the current policy regarding community contributor issues.
-
-## Implement design & UI elements
-
-This [documentation](design.md) outlines the current design and UI guidelines.
-
-## Issue tracker
-
-This [documentation](issue_workflow.md) outlines the issue tracker process.
-
-### Issue triaging
-
-This [documentation](issue_workflow.md) outlines the current issue triaging process.
-
-### Feature proposals
-
-This [documentation](issue_workflow.md) outlines the feature proposal process.
-
-### Issue tracker guidelines
-
-This [documentation](issue_workflow.md) outlines the issue tracker guidelines.
-
-### Issue weight
-
-This [documentation](issue_workflow.md) outlines the issue weight guidelines.
-
-### Regression issues
-
-This [documentation](issue_workflow.md) outlines the regression issue process.
-
-### Technical and UX debt
-
-This [documentation](issue_workflow.md) about technical and UX debt has been moved.
-
-### Stewardship
-
-This [documentation](issue_workflow.md) outlines the stewardship process.
+* [Type labels](issue_workflow.md#type-labels)
+* [Subject labels](issue_workflow.md#subject-labels)
+* [Team labels](issue_workflow.md#team-labels)
+* [Release Scoping labels](issue_workflow.md#release-scoping-labels)
+* [Priority labels](issue_workflow.md#priority-labels)
+* [Severity labels](issue_workflow.md#severity-labels)
+* [Label for community contributors](issue_workflow.md#label-for-community-contributors)
+* [Issue triaging](issue_workflow.md#issue-triaging)
+* [Feature proposals](issue_workflow.md#feature-proposals)
+* [Issue tracker guidelines](issue_workflow.md#issue-tracker-guidelines)
+* [Issue weight](issue_workflow.md#issue-weight)
+* [Regression issues](issue_workflow.md#regression-issues)
+* [Technical and UX debt](issue_workflow.md#technical-and-ux-debt)
+* [Stewardship](issue_workflow.md#stewardship)
 
 ## Merge requests
 
 This [documentation](merge_request_workflow.md) outlines the current merge request process.
 
-### Merge request guidelines
-
-This [documentation](merge_request_workflow.md) outlines the current merge request guidelines.
-
-### Contribution acceptance criteria
-
-This [documentation](merge_request_workflow.md) outlines the current acceptance criteria for contributions.
-
-## Definition of done
-
-This [documentation](merge_request_workflow.md) outlines the definition of done.
+* [Merge request guidelines](merge_request_workflow.md#merge-request-guidelines)
+* [Contribution acceptance criteria](merge_request_workflow.md#contribution-acceptance-criteria)
+* [Definition of done](merge_request_workflow.md#definition-of-done)
 
 ## Style guides
-This [documentation](design.md) outlines the current style guidelines.
+
+This [documentation](style_guides.md) outlines the current style guidelines.
 
 ---
 
 [Return to Development documentation](../README.md)
+
+[core team]: https://about.gitlab.com/core-team/
+[team]: https://about.gitlab.com/team/
+[getting-help]: https://about.gitlab.com/getting-help/
+[codetriage]: http://www.codetriage.com/gitlabhq/gitlabhq
diff --git a/doc/development/contributing/issue_workflow.md b/doc/development/contributing/issue_workflow.md
index 08042fa2aec..7c7da50a149 100644
--- a/doc/development/contributing/issue_workflow.md
+++ b/doc/development/contributing/issue_workflow.md
@@ -1,27 +1,4 @@
-<!-- START doctoc generated TOC please keep comment here to allow auto update -->
-<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
-**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
-
-- [Workflow labels](#workflow-labels)
-  - [Type labels](#type-labels)
-  - [Subject labels](#subject-labels)
-  - [Team labels](#team-labels)
-  - [Release Scoping labels](#release-scoping-labels)
-  - [Priority labels](#priority-labels)
-  - [Severity labels](#severity-labels)
-     - [Severity impact guidance](#severity-impact-guidance)
-  - [Label for community contributors](#label-for-community-contributors)
-  - [Issue triaging](#issue-triaging)
-  - [Feature proposals](#feature-proposals)
-  - [Issue tracker guidelines](#issue-tracker-guidelines)
-  - [Issue weight](#issue-weight)
-  - [Regression issues](#regression-issues)
-  - [Technical and UX debt](#technical-and-ux-debt)
-  - [Stewardship](#stewardship)
-
-<!-- END doctoc generated TOC please keep comment here to allow auto update -->
-
-## Workflow labels
+# Workflow labels
 
 To allow for asynchronous issue handling, we use [milestones][milestones-page]
 and [labels][labels-page]. Leads and product managers handle most of the
@@ -31,7 +8,8 @@ Most issues will have labels for at least one of the following:
 
 - Type: ~"feature proposal", ~bug, ~customer, etc.
 - Subject: ~wiki, ~"container registry", ~ldap, ~api, ~frontend, etc.
-- Team: ~"CI/CD", ~Plan, ~Manage, ~Quality, etc.
+- Team: ~Plan, ~Manage, ~Quality, etc.
+- Stage: ~"devops:plan", ~"devops:create", etc.
 - Release Scoping: ~Deliverable, ~Stretch, ~"Next Patch Release"
 - Priority: ~P1, ~P2, ~P3, ~P4
 - Severity: ~S1, ~S2, ~S3, ~S4
@@ -43,9 +21,8 @@ If you come across an issue that has none of these, and you're allowed to set
 labels, you can _always_ add the team and type, and often also the subject.
 
 [milestones-page]: https://gitlab.com/gitlab-org/gitlab-ce/milestones
-[labels-page]: https://gitlab.com/gitlab-org/gitlab-ce/labels
 
-### Type labels
+## Type labels
 
 Type labels are very important. They define what kind of issue this is. Every
 issue should have one or more.
@@ -61,7 +38,7 @@ already reserved for subject labels).
 
 The descriptions on the [labels page][labels-page] explain what falls under each type label.
 
-### Subject labels
+## Subject labels
 
 Subject labels are labels that define what area or feature of GitLab this issue
 hits. They are not always necessary, but very convenient.
@@ -75,7 +52,7 @@ issue is labeled with a subject label corresponding to your expertise.
 
 Subject labels are always all-lowercase.
 
-### Team labels
+## Team labels
 
 Team labels specify what team is responsible for this issue.
 Assigning a team label makes sure issues get the attention of the appropriate
@@ -83,8 +60,7 @@ people.
 
 The current team labels are:
 
-- ~Configuration
-- ~"CI/CD"
+- ~Configure
 - ~Create
 - ~Distribution
 - ~Documentation
@@ -97,6 +73,7 @@ The current team labels are:
 - ~Release
 - ~Secure
 - ~UX
+- ~Verify
 
 The descriptions on the [labels page][labels-page] explain what falls under the
 responsibility of each team.
@@ -107,7 +84,40 @@ indicate if an issue needs backend work, frontend work, or both.
 Team labels are always capitalized so that they show up as the first label for
 any issue.
 
-### Release Scoping labels
+## Stage labels
+
+Stage labels specify which [DevOps stage][devops-stages] the issue belongs to.
+
+The current stage labels are:
+
+- ~"devops:manage"
+- ~"devops:plan"
+- ~"devops:create"
+- ~"devops:verify"
+- ~"devops:package"
+- ~"devops:release"
+- ~"devops:configure"
+- ~"devops:monitor"
+- ~"devops:secure"
+
+These labels should be mutually exclusive. If an issue belongs to multiple
+stages, the most relevant should be used.
+
+They differ from the [Team labels](#team-labels) because teams may work on
+issues outside their stage.
+
+Normally there is a 1:1 relationship between Stage labels and Team labels, but
+any issue can be picked up by any team, depending on current priorities.
+So, an issue labeled ~"devops:create" may be scheduled by the ~Plan team, for
+example. In such cases, it's usual to include both team labels so each team can
+be aware of the progress.
+
+The Stage labels are used to generate the [direction pages][direction-pages] automatically.
+
+[devops-stages]: https://about.gitlab.com/direction/#devops-stages
+[direction-pages]: https://about.gitlab.com/direction/
+
+## Release Scoping labels
 
 Release Scoping labels help us clearly communicate expectations of the work for the
 release. There are three levels of Release Scoping labels:
@@ -131,14 +141,17 @@ Priority labels help us define the time a ~bug fix should be completed. Priority
 If there are multiple defects, the priority decides which defect has to be fixed immediately versus later.
 This label documents the planned timeline & urgency which is used to measure against our actual SLA on delivering ~bug fixes.
 
-| Label | Meaning         | Estimate time to fix                                             |
-|-------|-----------------|------------------------------------------------------------------|
-| ~P1   | Urgent Priority | The current release + potentially immediate hotfix to GitLab.com |
-| ~P2   | High Priority   | The next release                                                 |
-| ~P3   | Medium Priority | Within the next 3 releases (approx one quarter)                  |
-| ~P4   | Low Priority    | Anything outside the next 3 releases (approx beyond one quarter) |
+| Label | Meaning         | Defect SLA (applies only to ~bug and ~security defects)                                                    |
+|-------|-----------------|----------------------------------------------------------------------------|
+| ~P1   | Urgent Priority | The current release + potentially immediate hotfix to GitLab.com (30 days) |
+| ~P2   | High Priority   | The next release (60 days)                                                 |
+| ~P3   | Medium Priority | Within the next 3 releases (approx one quarter or 90 days)                 |
+| ~P4   | Low Priority    | Anything outside the next 3 releases (more than one quarter or 120 days)   |
 
-### Severity labels
+If an issue seems to fall between two priority labels, assign it to the higher-
+priority label.
+
+## Severity labels
 
 Severity labels help us clearly communicate the impact of a ~bug on users.
 
@@ -149,7 +162,11 @@ Severity labels help us clearly communicate the impact of a ~bug on users.
 | ~S3   | Major Severity    | Broken Feature, workaround acceptable                 | Can create merge requests only from the Merge Requests page, not through the Issue. |
 | ~S4   | Low Severity      | Functionality inconvenience or cosmetic issue         | Label colors are incorrect / not being displayed. |
 
-#### Severity impact guidance
+If an issue seems to fall between two severity labels, even taking the
+[severity impact guidance](#severity-impact-guidance) into account, assign
+it to the higher-severity label.
+
+### Severity impact guidance
 
 Severity levels can be applied further depending on the facet of the impact; e.g. Affected customers, GitLab.com availability, performance and etc. The below is a guideline.
 
@@ -158,16 +175,16 @@ Severity levels can be applied further depending on the facet of the impact; e.g
 | ~S1      | >50% users affected (possible company extinction level event)       | Significant impact on all of GitLab.com            |                              |
 | ~S2      | Many users or multiple paid customers affected (but not apocalyptic)| Significant impact on large portions of GitLab.com | Degradation is guaranteed to occur in the near future |
 | ~S3      | A few users or a single paid customer affected                      | Limited impact on important portions of GitLab.com | Degradation is likely to occur in the near future     |
-| ~S4      | No paid users/customer affected, or expected to in the near future  | Minor impact on on GitLab.com                      | Degradation _may_ occur but it's not likely           |
+| ~S4      | No paid users/customer affected, or expected to in the near future  | Minor impact on GitLab.com                         | Degradation _may_ occur but it's not likely           |
 
-### Label for community contributors
+## Label for community contributors
 
 Issues that are beneficial to our users, 'nice to haves', that we currently do
 not have the capacity for or want to give the priority to, are labeled as
-~"Accepting Merge Requests", so the community can make a contribution.
+~"Accepting merge requests", so the community can make a contribution.
 
 Community contributors can submit merge requests for any issue they want, but
-the ~"Accepting Merge Requests" label has a special meaning. It points to
+the ~"Accepting merge requests" label has a special meaning. It points to
 changes that:
 
 1. We already agreed on,
@@ -175,43 +192,42 @@ changes that:
 1. Are likely to get accepted by a maintainer.
 
 We want to avoid a situation when a contributor picks an
-~"Accepting Merge Requests" issue and then their merge request gets closed,
+~"Accepting merge requests" issue and then their merge request gets closed,
 because we realize that it does not fit our vision, or we want to solve it in a
 different way.
 
-We add the ~"Accepting Merge Requests" label to:
+We add the ~"Accepting merge requests" label to:
 
 - Low priority ~bug issues (i.e. we do not add it to the bugs that we want to
 solve in the ~"Next Patch Release")
 - Small ~"feature proposal"
 - Small ~"technical debt" issues
 
-After adding the ~"Accepting Merge Requests" label, we try to estimate the
+After adding the ~"Accepting merge requests" label, we try to estimate the
 [weight](#issue-weight) of the issue. We use issue weight to let contributors
 know how difficult the issue is. Additionally:
 
-- We advertise ["Accepting Merge Requests" issues with weight < 5][up-for-grabs]
+- We advertise [`Accepting merge requests` issues with weight < 5][up-for-grabs]
   as suitable for people that have never contributed to GitLab before on the
   [Up For Grabs campaign](http://up-for-grabs.net)
 - We encourage people that have never contributed to any open source project to
-  look for ["Accepting Merge Requests" issues with a weight of 1][firt-timers]
+  look for [`Accepting merge requests` issues with a weight of 1][firt-timers]
 
 If you've decided that you would like to work on an issue, please @-mention
 the [appropriate product manager](https://about.gitlab.com/handbook/product/#who-to-talk-to-for-what)
 as soon as possible. The product manager will then pull in appropriate GitLab team
 members to further discuss scope, design, and technical considerations. This will
-ensure that that your contribution is aligned with the GitLab product and minimize
+ensure that your contribution is aligned with the GitLab product and minimize
 any rework and delay in getting it merged into master.
 
-GitLab team members who apply the ~"Accepting Merge Requests" label to an issue
+GitLab team members who apply the ~"Accepting merge requests" label to an issue
 should update the issue description with a responsible product manager, inviting
 any potential community contributor to @-mention per above.
 
-[up-for-grabs]: https://gitlab.com/gitlab-org/gitlab-ce/issues?label_name=Accepting+Merge+Requests&scope=all&sort=weight_asc&state=opened
-[firt-timers]: https://gitlab.com/gitlab-org/gitlab-ce/issues?label_name%5B%5D=Accepting+Merge+Requests&scope=all&sort=upvotes_desc&state=opened&weight=1
+[up-for-grabs]: https://gitlab.com/groups/gitlab-org/-/issues?state=opened&label_name[]=Accepting+merge+requests&assignee_id=0&sort=weight
+[firt-timers]: https://gitlab.com/groups/gitlab-org/-/issues?state=opened&label_name[]=Accepting+merge+requests&assignee_id=0&sort=weight&weight=1
 
-
-### Issue triaging
+## Issue triaging
 
 Our issue triage policies are [described in our handbook]. You are very welcome
 to help the GitLab team triage issues. We also organize [issue bash events] once
@@ -224,7 +240,7 @@ on those issues. Please select someone with relevant experience from the
 the commit history for the affected files to find someone.
 
 We also use [GitLab Triage] to automate some triaging policies. This is
-currently setup as a [scheduled pipeline] running on [quality/triage-ops]
+currently set up as a [scheduled pipeline] running on [quality/triage-ops]
 project.
 
 [described in our handbook]: https://about.gitlab.com/handbook/engineering/issue-triage/
@@ -232,8 +248,9 @@ project.
 [GitLab Triage]: https://gitlab.com/gitlab-org/gitlab-triage
 [scheduled pipeline]: https://gitlab.com/gitlab-org/quality/triage-ops/pipeline_schedules/10512/edit
 [quality/triage-ops]: https://gitlab.com/gitlab-org/quality/triage-ops
+[team]: https://about.gitlab.com/team/
 
-### Feature proposals
+## Feature proposals
 
 To create a feature proposal for CE, open an issue on the
 [issue tracker of CE][ce-tracker].
@@ -250,7 +267,7 @@ code snippet right after your description in a new line: `~"feature proposal"`.
 Please keep feature proposals as small and simple as possible, complex ones
 might be edited to make them small and simple.
 
-Please submit Feature Proposals using the ['Feature Proposal' issue template](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.gitlab/issue_templates/Feature%20Proposal.md) provided on the issue tracker.
+Please submit Feature Proposals using the ['Feature Proposal' issue template](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.gitlab/issue_templates/Feature%20proposal.md) provided on the issue tracker.
 
 For changes in the interface, it is helpful to include a mockup. Issues that add to, or change, the interface should
 be given the ~"UX" label. This will allow the UX team to provide input and guidance. You may
@@ -259,7 +276,9 @@ need to ask one of the [core team] members to add the label, if you do not have
 If you want to create something yourself, consider opening an issue first to
 discuss whether it is interesting to include this in GitLab.
 
-### Issue tracker guidelines
+[fpl]: https://gitlab.com/gitlab-org/gitlab-ce/issues?label_name=feature+proposal
+
+## Issue tracker guidelines
 
 **[Search the issue tracker][ce-tracker]** for similar entries before
 submitting your own, there's a good chance somebody else had the same issue or
@@ -271,7 +290,7 @@ The text in the parenthesis is there to help you with what to include. Omit it
 when submitting the actual issue. You can copy-paste it and then edit as you
 see fit.
 
-### Issue weight
+## Issue weight
 
 Issue weight allows us to get an idea of the amount of work required to solve
 one or multiple issues. This makes it possible to schedule work more accurately.
@@ -293,7 +312,7 @@ is probably 1, adding a new Git Hook maybe 4 or 5, big features 7-9.
 issues or chunks. You can simply not set the weight of a parent issue and set
 weights to children issues.
 
-### Regression issues
+## Regression issues
 
 Every monthly release has a corresponding issue on the CE issue tracker to keep
 track of functionality broken by that release and any fixes that need to be
@@ -313,7 +332,7 @@ addressed.
 [8.3 Regressions]: https://gitlab.com/gitlab-org/gitlab-ce/issues/4127
 [update the notes]: https://gitlab.com/gitlab-org/release-tools/blob/master/doc/pro-tips.md#update-the-regression-issue
 
-### Technical and UX debt
+## Technical and UX debt
 
 In order to track things that can be improved in GitLab's codebase,
 we use the ~"technical debt" label in [GitLab's issue tracker][ce-tracker].
@@ -337,7 +356,46 @@ for a release by the appropriate person.
 Make sure to mention the merge request that the ~"technical debt" issue or
 ~"UX debt" issue is associated with in the description of the issue.
 
-### Stewardship
+## Technical debt in follow-up issues
+
+It's common to discover technical debt during development of a new feature. In
+the spirit of "minimum viable change", resolution is often deferred to a
+follow-up issue. However, this cannot be used as an excuse to merge poor-quality
+code that would otherwise not pass review, or to overlook trivial matters that
+don't deserve the be scheduled independently, and would be best resolved in the
+original merge request - or not tracked at all!
+
+The overheads of scheduling, and rate of change in the GitLab codebase, mean
+that the cost of a trivial technical debt issue can quickly exceed the value of
+tracking it. This generally means we should resolve these in the original merge
+request - or simply not create a follow-up issue at all.
+
+For example, a typo in a comment that is being copied between files is worth
+fixing in the same MR, but not worth creating a follow-up issue for. Renaming a
+method that is used in many places to make its intent slightly clearer may be
+worth fixing, but it should not happen in the same MR, and is generally not
+worth the overhead of having an issue of its own. These issues would invariably
+be labelled `~P4 ~S4` if we were to create them.
+
+More severe technical debt can have implications for development velocity. If
+it isn't addressed in a timely manner, the codebase becomes needlessly difficult
+to change, new features become difficult to add, and regressions abound.
+
+Discoveries of this kind of technical debt should be treated seriously, and
+while resolution in a follow-up issue may be appropriate, maintainers should
+generally obtain a scheduling commitment from the author of the original MR, or
+the engineering or product manager for the relevant area. This may take the form
+of appropriate Priority / Severity labels on the issue, or an explicit milestone
+and assignee.
+
+The maintainer must always agree before an outstanding discussion is resolved in
+this manner, and will be the one to create the issue. The title and description
+should be of the same quality as those created
+[in the usual manner](#technical-and-ux-debt) - in particular, the issue title
+**must not** begin with `Follow-up`! The creating maintainer should also expect
+to be involved in some capacity when work begins on the follow-up issue.
+
+## Stewardship
 
 For issues related to the open source stewardship of GitLab,
 there is the ~"stewardship" label.
@@ -355,3 +413,7 @@ A recent example of this was the issue for
 ---
 
 [Return to Contributing documentation](index.md)
+
+[labels-page]: https://gitlab.com/gitlab-org/gitlab-ce/labels
+[ce-tracker]: https://gitlab.com/gitlab-org/gitlab-ce/issues
+[ee-tracker]: https://gitlab.com/gitlab-org/gitlab-ee/issues
diff --git a/doc/development/contributing/merge_request_workflow.md b/doc/development/contributing/merge_request_workflow.md
index 685287f7a0c..5b32b5cd46f 100644
--- a/doc/development/contributing/merge_request_workflow.md
+++ b/doc/development/contributing/merge_request_workflow.md
@@ -1,22 +1,10 @@
-<!-- START doctoc generated TOC please keep comment here to allow auto update -->
-<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
-**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
-
-- [Merge requests](#merge-requests)
-  - [Merge request guidelines](#merge-request-guidelines)
-  - [Contribution acceptance criteria](#contribution-acceptance-criteria)
-- [Definition of done](#definition-of-done)
-
-<!-- END doctoc generated TOC please keep comment here to allow auto update -->
-
-## Merge requests
+# Merge requests
 
 We welcome merge requests with fixes and improvements to GitLab code, tests,
 and/or documentation. The issues that are specifically suitable for
-community contributions are listed with the label
-[`Accepting Merge Requests` on our issue tracker for CE][accepting-mrs-ce]
-and [EE][accepting-mrs-ee], but you are free to contribute to any other issue
-you want.
+community contributions are listed with
+[the `Accepting merge requests` label](issue_workflow.md#label-for-community-contributors),
+but you are free to contribute to any other issue you want.
 
 Please note that if an issue is marked for the current milestone either before
 or while you are working on it, a team member may take over the merge request
@@ -30,13 +18,16 @@ wireframes if the feature will also change the UI.
 Merge requests should be opened at [GitLab.com][gitlab-mr-tracker].
 
 If you are new to GitLab development (or web development in general), see the
-[I want to contribute!](#i-want-to-contribute) section to get you started with
+[I want to contribute!](index.md#i-want-to-contribute) section to get you started with
 some potentially easy issues.
 
 To start with GitLab development download the [GitLab Development Kit][gdk] and
-see the [Development section](../README.md) for some guidelines.
+see the [Development section](../../README.md) for some guidelines.
+
+[gitlab-mr-tracker]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests
+[gdk]: https://gitlab.com/gitlab-org/gitlab-development-kit
 
-### Merge request guidelines
+## Merge request guidelines
 
 If you can, please submit a merge request with the fix or improvements
 including tests. If you don't know how to fix the issue but can write a test
@@ -114,7 +105,11 @@ Please ensure that your merge request meets the contribution acceptance criteria
 When having your code reviewed and when reviewing merge requests please take the
 [code review guidelines](../code_review.md) into account.
 
-### Contribution acceptance criteria
+[git-squash]: https://git-scm.com/book/en/Git-Tools-Rewriting-History#Squashing-Commits
+[closed-merge-requests]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests?assignee_id=&label_name=&milestone_id=&scope=&sort=&state=closed
+[team]: https://about.gitlab.com/team/
+
+## Contribution acceptance criteria
 
 1. The change is as small as possible
 1. Include proper tests and make all tests pass (unless it contains a test
@@ -144,7 +139,7 @@ When having your code reviewed and when reviewing merge requests please take the
    [polling with ETag caching][polling-etag].
 1. Changes after submitting the merge request should be in separate commits
    (no squashing).
-1. It conforms to the [style guides](#style-guides) and the following:
+1. It conforms to the [style guides](style_guides.md) and the following:
     - If your change touches a line that does not follow the style, modify the
       entire line to follow it. This prevents linting tools from generating warnings.
     - Don't touch neighbouring lines. As an exception, automatic mass
@@ -155,6 +150,9 @@ When having your code reviewed and when reviewing merge requests please take the
    "license-finder" test with a "Dependencies that need approval" error.
 1. The merge request meets the [definition of done](#definition-of-done).
 
+[license-finder-doc]: ../licensing.md
+[polling-etag]: ../polling.md
+
 ## Definition of done
 
 If you contribute to GitLab please know that changes involve more than just
@@ -167,12 +165,13 @@ the feature you contribute through all of these steps.
 1. Performance/scalability implications have been considered, addressed, and tested
 1. [Documented][doc-guidelines] in the `/doc` directory
 1. [Changelog entry added][changelog], if necessary
-1. Reviewed and any concerns are addressed
+1. Reviewed by UX/FE/BE and any concerns are addressed
 1. Merged by a project maintainer
 1. Added to the release blog article, if relevant
 1. Added to [the website](https://gitlab.com/gitlab-com/www-gitlab-com/), if relevant
 1. Community questions answered
 1. Answers to questions radiated (in docs/wiki/support etc.)
+1. [Black-box tests/end-to-end tests](../testing_guide/testing_levels.md#black-box-tests-or-end-to-end-tests) added if required. Please contact [the quality team](https://about.gitlab.com/handbook/engineering/quality/#teams) with any questions  
 
 If you add a dependency in GitLab (such as an operating system package) please
 consider updating the following and note the applicability of each in your
@@ -186,6 +185,12 @@ merge request:
 1. Test suite https://gitlab.com/gitlab-org/gitlab-ce/blob/master/scripts/prepare_build.sh
 1. Omnibus package creator https://gitlab.com/gitlab-org/omnibus-gitlab
 
+[definition-of-done]: http://guide.agilealliance.org/guide/definition-of-done.html
+[testing]: ../testing_guide/index.md  
+
 ---
 
 [Return to Contributing documentation](index.md)
+
+[changelog]: ../changelog.md "Generate a changelog entry"
+[doc-guidelines]: ../documentation/index.md "Documentation guidelines"
diff --git a/doc/development/contributing/style_guides.md b/doc/development/contributing/style_guides.md
new file mode 100644
index 00000000000..6f1ba5d62a5
--- /dev/null
+++ b/doc/development/contributing/style_guides.md
@@ -0,0 +1,39 @@
+# Style guides
+
+1. [Ruby](https://github.com/bbatsov/ruby-style-guide).
+   Important sections include [Source Code Layout][rss-source] and
+   [Naming][rss-naming]. Use:
+   - multi-line method chaining style **Option A**: dot `.` on the second line
+   - string literal quoting style **Option A**: single quoted by default
+1. [Rails](https://github.com/bbatsov/rails-style-guide)
+1. [Newlines styleguide][newlines-styleguide]
+1. [Testing][testing]
+1. [JavaScript styleguide][js-styleguide]
+1. [SCSS styleguide][scss-styleguide]
+1. [Shell commands](../shell_commands.md) created by GitLab
+   contributors to enhance security
+1. [Database Migrations](../migration_style_guide.md)
+1. [Markdown](http://www.cirosantilli.com/markdown-styleguide)
+1. [Documentation styleguide](../documentation/styleguide.md)
+1. Interface text should be written subjectively instead of objectively. It
+   should be the GitLab core team addressing a person. It should be written in
+   present time and never use past tense (has been/was). For example instead
+   of _prohibited this user from being saved due to the following errors:_ the
+   text should be _sorry, we could not create your account because:_
+1. Code should be written in [US English][us-english]
+
+This is also the style used by linting tools such as
+[RuboCop](https://github.com/bbatsov/rubocop) and [Hound CI](https://houndci.com).
+
+---
+
+[Return to Contributing documentation](index.md)
+
+[rss-source]: https://github.com/bbatsov/ruby-style-guide/blob/master/README.md#source-code-layout
+[rss-naming]: https://github.com/bbatsov/ruby-style-guide/blob/master/README.md#naming
+[doc-guidelines]: ../documentation/index.md "Documentation guidelines"
+[js-styleguide]: ../fe_guide/style_guide_js.md "JavaScript styleguide"
+[scss-styleguide]: ../fe_guide/style_guide_scss.md "SCSS styleguide"
+[newlines-styleguide]: ../newlines_styleguide.md "Newlines styleguide"
+[testing]: ../testing_guide/index.md
+[us-english]: https://en.wikipedia.org/wiki/American_English
diff --git a/doc/development/database_debugging.md b/doc/development/database_debugging.md
index 9c31265e417..b2c804b2ff0 100644
--- a/doc/development/database_debugging.md
+++ b/doc/development/database_debugging.md
@@ -33,7 +33,7 @@ If your test DB is giving you problems, it is safe to nuke it because it doesn't
  - `bundle exec rake db:migrate RAILS_ENV=development`: Execute any pending migrations that you may have picked up from a MR
  - `bundle exec rake db:migrate:status RAILS_ENV=development`: Check if all migrations are `up` or `down`
  - `bundle exec rake db:migrate:down VERSION=20170926203418 RAILS_ENV=development`: Tear down a migration
- - `bundle exec rake db:migrate:up VERSION=20170926203418 RAILS_ENV=development`: Setup a migration
+ - `bundle exec rake db:migrate:up VERSION=20170926203418 RAILS_ENV=development`: Set up a migration
  - `bundle exec rake db:migrate:redo VERSION=20170926203418 RAILS_ENV=development`: Re-run a specific migration
 
 
diff --git a/doc/development/database_merge_request_checklist.md b/doc/development/database_merge_request_checklist.md
index 75c395b61ef..48864c81592 100644
--- a/doc/development/database_merge_request_checklist.md
+++ b/doc/development/database_merge_request_checklist.md
@@ -1,15 +1,15 @@
 # Merge Request Checklist
 
 When creating a merge request that performs database related changes (schema
-changes, adjusting queries to optimise performance, etc) you should use the
-merge request template called "Database Changes". This template contains a
+changes, adjusting queries to optimize performance, etc) you should use the
+merge request template called "Database changes". This template contains a
 checklist of steps to follow to make sure the changes are up to snuff.
 
 To use the checklist, create a new merge request and click on the "Choose a
-template" dropdown, then click "Database Changes".
+template" dropdown, then click "Database changes".
 
 An example of this checklist can be found at
-https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12463.
+<https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12463>.
 
 The source code of the checklist can be found in at
-https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.gitlab/merge_request_templates/Database%20Changes.md
+<https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.gitlab/merge_request_templates/Database%20changes.md>
diff --git a/doc/development/db_dump.md b/doc/development/db_dump.md
index e4ff72aa349..97762a62a80 100644
--- a/doc/development/db_dump.md
+++ b/doc/development/db_dump.md
@@ -13,7 +13,7 @@ large database imports.
 ```
 # On STAGING
 echo "postgresql['checkpoint_segments'] = 64" | sudo tee -a /etc/gitlab/gitlab.rb
-sudo touch /etc/gitlab/skip-auto-migrations
+sudo touch /etc/gitlab/skip-auto-reconfigure
 sudo gitlab-ctl reconfigure
 sudo gitlab-ctl stop unicorn
 sudo gitlab-ctl stop sidekiq
diff --git a/doc/development/diffs.md b/doc/development/diffs.md
index 5e8e8cc7541..43fc125c21d 100644
--- a/doc/development/diffs.md
+++ b/doc/development/diffs.md
@@ -2,13 +2,10 @@
 
 Currently we rely on different sources to present 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
 
 ### Merge request diffs
@@ -19,20 +16,21 @@ we fetch the comparison information using `Gitlab::Git::Compare`, which fetches
 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.
+Even though diffs larger than 10% of the value of `ApplicationSettings#diff_max_patch_bytes` are collapsed,
+we still keep them on Postgres. However, diff files larger than defined _safety limits_
+(see the [Diff limits section](#diff-limits)) are _not_ persisted in the database.
 
 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`
+1. Fetch the _old_ and _new_ file blobs in batch to:
+   - Highlight old and new file content
+   - Know which viewer it should use for each file (text, image, deleted, etc)
+   - Know if the file content changed
+   - Know if it was stored externally
+   - Know if it had storage errors
+1. If the diff file is cacheable (text-based), it's cached on Redis
+   using `Gitlab::Diff::FileCollection::MergeRequestDiff`
 
 ### Note diffs
 
@@ -41,9 +39,9 @@ on `NoteDiffFile` (which is associated with the actual `DiffNote`). So instead
 of hitting the repository every time we need the diff of the file, we:
 
 1. Check whether we have the `NoteDiffFile#diff` persisted and use it
-2. Otherwise, if it's a current MR revision, use the persisted
-`MergeRequestDiffFile#diff`
-3. In the last scenario, go the the repository and fetch the diff
+1. Otherwise, if it's a current MR revision, use the persisted
+   `MergeRequestDiffFile#diff`
+1. In the last scenario, go the repository and fetch the diff
 
 ## Diff limits
 
@@ -102,23 +100,20 @@ Gitaly will only return the safe amount of data to be persisted on `merge_reques
 
 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
-```
+#### Expandable patches (collapsed)
 
-File diff will be collapsed (but be expandable) if it is larger than 10 kilobytes.
+Diff patches are collapsed when surpassing 10% of the value set in `ApplicationSettings#diff_max_patch_bytes`.
+That is, it's equivalent to 10kb if the maximum allowed value is 100kb.
+The diff will still be persisted and expandable if the patch size doesn't
+surpass `ApplicationSettings#diff_max_patch_bytes`.
 
 *Note:* Although this nomenclature (Collapsing) is also used on Gitaly, this limit is only used on GitLab (hardcoded - not sent to Gitaly).
 Gitaly will only return `Diff.Collapsed` (RPC) when surpassing collection limits.
 
-```ruby
-Gitlab::Git::Diff::SIZE_LIMIT = 100.kilobytes
-```
-
-File diff will not be rendered if it's larger than 100 kilobytes.
+#### Not expandable patches (too large)
 
-*Note:* This limit is currently hardcoded and applied on Gitaly and the RPC returns `Diff.TooLarge` when this limit is surpassed.
-Although we're still also applying it on GitLab, we should remove the redundancy from GitLab once we're confident with the Gitaly integration.
+The patch not be rendered if it's larger than `ApplicationSettings#diff_max_patch_bytes`.
+Users will see a `This source diff could not be displayed because it is too large` message.
 
 ```ruby
 Commit::DIFF_SAFE_LINES = Gitlab::Git::DiffCollection::DEFAULT_LIMITS[:max_lines] = 5000
diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md
index d6ae4cb39f0..b7990e1b558 100644
--- a/doc/development/documentation/index.md
+++ b/doc/development/documentation/index.md
@@ -4,9 +4,9 @@ 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).
+- **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
 
@@ -41,15 +41,17 @@ how to structure GitLab docs.
 
 ## 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.
+[GitLab docs](https://gitlab.com/gitlab-com/gitlab-docs) uses [GitLab Kramdown](https://gitlab.com/gitlab-org/gitlab_kramdown)
+as markdown engine. Check the [GitLab Markdown Kramdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/)
+for a complete Kramdown reference.
 
-All the docs follow the [documentation style guidelines](styleguide.md).
+Follow the [documentation style guidelines](styleguide.md) strictly.
 
 ## 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). 
+[`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.
@@ -61,11 +63,11 @@ in small iterations. Please don't create new docs in these folders.
 ### Documentation files
 
 - When you create a new directory, always start with an `index.md` file.
-Do not use another file name and **do not** create `README.md` files
+  Do not use another file name and **do not** create `README.md` files.
 - **Do not** use special chars and spaces, or capital letters in file names,
-directory names, branch names, and anything that generates a path.
-- Max screenshot size: 100KB
-- We do not support videos (yet)
+  directory names, branch names, and anything that generates a path.
+- Max screenshot size: 100KB.
+- We do not support videos (yet).
 
 ### Location and naming documents
 
@@ -83,24 +85,21 @@ 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) |
+| 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 & best practices:**
 
-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
@@ -134,13 +133,13 @@ merge request.
 
 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
+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:
 
-```
+```md
 This document was moved to [another location](path/to/new_doc.md).
 ```
 
@@ -154,7 +153,7 @@ For example, if you were to move `doc/workflow/lfs/lfs_administration.md` to
 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:
 
-    ```
+    ```md
     This document was moved to [another location](../../administration/lfs.md).
     ```
 
@@ -162,7 +161,7 @@ For example, if you were to move `doc/workflow/lfs/lfs_administration.md` to
    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:
 
-    ```
+    ```sh
     git grep -n "workflow/lfs/lfs_administration"
     git grep -n "lfs/lfs_administration"
     ```
@@ -198,6 +197,11 @@ 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`.
 
+NOTE: **Note:**
+This redirection method will not provide a redirect fallback on GitLab `/help`. When using
+it, make sure to add a link to the new page on the doc, otherwise it's a dead end for users that
+land on the doc via `/help`.
+
 ### Redirections for pages with Disqus comments
 
 If the documentation page being relocated already has any Disqus comments,
@@ -223,33 +227,14 @@ 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 |
-| ----------- | ------------- |
+| 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` |
@@ -257,15 +242,6 @@ choices:
 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).
 
-## Danger bot
-
-GitLab uses [danger bot](https://github.com/danger/danger) for some elements in
-code review. For docs changes in merge requests, the following actions are taken:
-
-1. Whenever a change under `/doc` is made, the bot leaves a comment for the
-   author to mention `@gl-docsteam`, so that the docs can be properly
-   reviewed.
-
 ## Merge requests for GitLab documentation
 
 Before getting started, make sure you read the introductory section
@@ -278,7 +254,6 @@ for GitLab Team members.
 - 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
@@ -299,112 +274,15 @@ Follow this [method for cherry-picking from CE to EE](../automatic_ce_ee_merge.m
 - 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
+  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.
+  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.
+  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)
+  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.
 
 ## GitLab `/help`
 
@@ -413,8 +291,8 @@ Every GitLab instance includes the documentation, which is available from `/help
 
 The documentation available online on docs.gitlab.com is continuously
 deployed every hour from the `master` branch of CE, EE, Omnibus, and Runner. Therefore,
-once a merge request gets merged, it will be available online on the same day,
-but they will be shipped (and available on `/help`) within the milestone assigned
+once a merge request gets merged, it will be available online on the same day.
+However, they will be shipped (and available on `/help`) within the milestone assigned
 to the MR.
 
 For instance, let's say your merge request has a milestone set to 11.3, which
@@ -511,7 +389,7 @@ They should be placed in a new directory named `/article-title/index.md` under a
 - **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
+- **Tutorials**: technical content provided step-by-step on how to do things, or how to reach specific objectives
 
 #### Understanding guides, tutorials, and technical overviews
 
@@ -543,7 +421,6 @@ with the following information:
 
 For example:
 
-
 ```yaml
 ---
 author: John Doe
@@ -558,5 +435,250 @@ date: 2017-02-01
 
 Use the [writing method](https://about.gitlab.com/handbook/product/technical-writing/#writing-method) defined by the Technical Writing team.
 
+## 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-when-contributing-to-gitlab-documentation) or [these instructions for GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/gitlab_docs.md).
+
+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
+
+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.
+
+### Troubleshooting review apps
+
+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.
+
+### Technical aspects
+
+If you want to know the in-depth 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)
+
+## 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.
+
+### Linting
+
+To help adhere to the [documentation style guidelines](styleguide.md), and to improve the content
+added to documentation, consider locally installing and running documentation linters. This will
+help you catch common issues before raising merge requests for review of documentation.
+
+The following are some suggested linters you can install locally and sample configuration:
+
+- [`proselint`](#proselint)
+- [`markdownlint`](#markdownlint)
+
+NOTE: **Note:**
+This list does not limit what other linters you can add to your local documentation writing toolchain.
+
+#### `proselint`
+
+`proselint` checks for common problems with English prose. It provides a
+ [plethora of checks](http://proselint.com/checks/) that are helpful for technical writing.
+
+`proselint` can be used [on the command line](http://proselint.com/utility/), either on a single
+ Markdown file or on all Markdown files in a project. For example, to run `proselint` on all
+ documentation in the [`gitlab-ce` project](https://gitlab.com/gitlab-org/gitlab-ce), run the
+ following commands from within the `gitlab-ce` project:
+
+```sh
+cd doc
+proselint **/*.md
+```
+
+`proselint` can also be run from within editors using plugins. For example, the following plugins
+ are available:
+
+- [Sublime Text](https://packagecontrol.io/packages/SublimeLinter-contrib-proselint)
+- [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=PatrykPeszko.vscode-proselint)
+- [Others](https://github.com/amperser/proselint#plugins-for-other-software)
+
+##### Sample `proselint` configuration
+
+All of the checks are good to use. However, excluding the `typography.symbols` and `misc.phrasal_adjectives` checks will reduce
+noise. The following sample `proselint` configuration disables these checks:
+
+```json
+{
+  "checks": {
+    "typography.symbols": false,
+    "misc.phrasal_adjectives": false
+  }
+}
+```
+
+A file with `proselint` configuration must be placed in a
+[valid location](https://github.com/amperser/proselint#checks). For example, `~/.config/proselint/config`.
+
+#### `markdownlint`
+
+`markdownlint` checks that certain rules ([example](https://github.com/DavidAnson/markdownlint/blob/master/README.md#rules--aliases))
+ are followed for Markdown syntax. Our [style guidelines](styleguide.md) elaborate on which choices
+ must be made when selecting Markdown syntax for GitLab documentation and this tool helps
+ catch deviations from those guidelines.
+
+`markdownlint` can be used [on the command line](https://github.com/igorshubovych/markdownlint-cli#markdownlint-cli--),
+ either on a single Markdown file or on all Markdown files in a project. For example, to run
+ `markdownlint` on all documentation in the [`gitlab-ce` project](https://gitlab.com/gitlab-org/gitlab-ce),
+ run the following commands from within the `gitlab-ce` project:
+
+```sh
+cd doc
+markdownlint **/*.md
+```
+
+`markdownlint` can also be run from within editors using plugins. For example, the following plugins
+ are available:
+
+- [Sublime Text](https://packagecontrol.io/packages/SublimeLinter-contrib-markdownlint)
+- [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint)
+- [Others](https://github.com/DavidAnson/markdownlint#related)
+
+##### Sample `markdownlint` configuration
+
+The following sample `markdownlint` configuration modifies the available default rules to:
+
+- Adhere to the [style guidelines](styleguide.md).
+- Apply conventions found in the GitLab documentation.
+- Allow the flexibility of using some inline HTML.
+
+```json
+{
+  "default": true,
+  "header-style": { "style": "atx" },
+  "ul-style": { "style": "dash" },
+  "line-length": false,
+  "no-trailing-punctuation": false,
+  "ol-prefix": { "style": "one" },
+  "blanks-around-fences": false,
+  "no-inline-html": {
+    "allowed_elements": [
+      "table",
+      "tbody",
+      "tr",
+      "td",
+      "ul",
+      "ol",
+      "li",
+      "br",
+      "img",
+      "a",
+      "strong",
+      "i",
+      "div"
+    ]
+  },
+  "hr-style": { "style": "---" },
+  "fenced-code-language": false
+}
+```
+
+For [`markdownlint`](https://github.com/DavidAnson/markdownlint/), this configuration must be
+placed in a [valid location](https://github.com/igorshubovych/markdownlint-cli#configuration). For
+example, `~/.markdownlintrc`.
+
+## Danger bot
+
+GitLab uses [danger bot](https://github.com/danger/danger) for some elements in
+code review. For docs changes in merge requests, whenever a change under `/doc`
+is made, the bot leaves a comment for the author to mention `@gl-docsteam`, so
+that the docs can be properly reviewed.
+
 [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/structure.md b/doc/development/documentation/structure.md
index 1002836096a..607ad21d459 100644
--- a/doc/development/documentation/structure.md
+++ b/doc/development/documentation/structure.md
@@ -21,21 +21,21 @@ Before getting started, read through the following docs:
 Every document should include the following content in the following sequence:
 
 - **Feature name**: defines an intuitive name for the feature that clearly
-states what it is and is consistent with any relevant UI text.
+  states what it is and is consistent with any relevant UI text.
 - **Feature overview** and description: describe what it is, what it does, and in what context it should be used.
 - **Use cases**: describes real use case scenarios for that feature.
 - **Requirements**: describes what software and/or configuration is required to be able to
-use the feature and, if applicable, prerequisite knowledge for being able to follow/implement the tutorial.
-For example, familiarity with GitLab CI/CD, an account on a third-party service, dependencies installed, etc.
-Link each one to its most relevant resource; i.e., where the reader can go to begin to fullfil that requirement.
-(Another doc page, a third party application's site, etc.)
+  use the feature and, if applicable, prerequisite knowledge for being able to follow/implement the tutorial.
+  For example, familiarity with GitLab CI/CD, an account on a third-party service, dependencies installed, etc.
+  Link each one to its most relevant resource; i.e., where the reader can go to begin to fullfil that requirement.
+  (Another doc page, a third party application's site, etc.)
 - **Instructions**: clearly describes the steps to use the feature, leaving no gaps.
 - **Troubleshooting** guide (recommended but not required): if you know beforehand what issues
-one might have when setting it up, or when something is changed, or on upgrading, it's
-important to describe those too. Think of things that may go wrong and include them in the
-docs. This is important to minimize requests for support, and to avoid doc comments with
-questions that you know someone might ask. Answering them beforehand only makes your
-document better and more approachable.
+  one might have when setting it up, or when something is changed, or on upgrading, it's
+  important to describe those too. Think of things that may go wrong and include them in the
+  docs. This is important to minimize requests for support, and to avoid doc comments with
+  questions that you know someone might ask. Answering them beforehand only makes your
+  document better and more approachable.
 
 For additional details, see the subsections below, as well as the [Documentation template for new docs](#Documentation-template-for-new-docs).
 
@@ -55,10 +55,11 @@ You should answer this question: what can you do with this feature/change? Use c
 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)
+
+- CE and EE: [Issues](../../user/project/issues/index.md#use-cases)
+- CE and EE: [Merge Requests](../../user/project/merge_requests/index.md)
+- EE-only: [Geo](https://docs.gitlab.com/ee/administration/geo/replication/index.html)
+- EE-only: [Jenkins integration](https://docs.gitlab.com/ee/integration/jenkins.html)
 
 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
@@ -72,14 +73,14 @@ and for every **major** feature present in Community Edition.
 Your new document will be discoverable by the user only if:
 
 - Crosslinked from the higher-level index (e.g., Issue Boards docs
-should be linked from Issues; Prometheus docs should be linked from
-Monitoring; CI/CD tutorials should be linked from CI/CD examples).
+  should be linked from Issues; Prometheus docs should be linked from
+  Monitoring; CI/CD tutorials should be linked from CI/CD examples).
   - When referencing other GitLab products and features, link to their
-respective docs; when referencing third-party products or technologies,
-link out to their external sites, documentation, and resources.
+  respective docs; when referencing third-party products or technologies,
+  link out to their external sites, documentation, and resources.
 - The headings are clear. E.g., "App testing" is a bad heading, "Testing
-an application with GitLab CI/CD" is much better. Think of something
-someone will search for and use these keywords in the headings.
+  an application with GitLab CI/CD" is much better. Think of something
+  someone will search for and use these keywords in the headings.
 
 ## Documentation template for new docs
 
@@ -133,7 +134,7 @@ is simple and the document is short.
 - Be clear, concise, and stick to the goal of the doc: explain how to
 use that feature.
 - Use inclusive language and avoid jargons, as well as uncommon and
-fancy words. The docs should be clear and very easy to understand.
+fancy words. The docs should be clear and easy to understand.
 - Write in the 3rd person (use "we", "you", "us", "one", instead of "I" or "me").
 - Always provide internal and external reference links.
 - Always link the doc from its higher-level index.
@@ -141,9 +142,49 @@ fancy words. The docs should be clear and very easy to understand.
 <!-- ## Troubleshooting
 
 Add a troubleshooting guide when possible/applicable. -->
-```
+
+---
 
 Notes:
 
-- (1): Apply the [tier badges](styleguide.md#product-badges) accordingly
-- (2): Apply the correct format for the [GitLab version introducing the feature](styleguide.md#gitlab-versions-and-tiers)
+- (1): Apply the [tier badges](https://docs.gitlab.com/ee/development/documentation/styleguide.html#product-badges) accordingly
+- (2): Apply the correct format for the [GitLab version introducing the feature](https://docs.gitlab.com/ee/development/documentation/styleguide.html#gitlab-versions-and-tiers)
+```
+
+## Help and feedback section
+
+The "help and feedback" section (introduced by [!319](https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/319)) displayed at the end of each document
+can be omitted from the doc by adding a key into the its frontmatter:
+
+```yaml
+---
+feedback: false
+---
+```
+
+The default is to leave it there. If you want to omit it from a document,
+you must check with a technical writer before doing so.
+
+### Disqus
+
+We also have integrated the docs site with Disqus (introduced by
+[!151](https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/151)),
+allowing our users to post comments.
+
+To omit only the comments from the feedback section, use the following
+key on the frontmatter:
+
+```yaml
+---
+comments: false
+---
+```
+
+We are only hiding comments in main index pages, such as [the main documentation index](../../README.md), since its content is too broad to comment on. Before omitting Disqus,
+you must check with a technical writer.
+
+Note that once `feedback: false` is added to the frontmatter, it will automatically omit
+Disqus, therefore, don't add both keys to the same document.
+
+The click events in the feedback section are tracked with Google Tag Manager. The
+conversions can be viewed on Google Analytics by navigating to **Behavior > Events > Top events > docs**.
diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md
index 8083f219d4a..8309ba9a72c 100644
--- a/doc/development/documentation/styleguide.md
+++ b/doc/development/documentation/styleguide.md
@@ -10,15 +10,15 @@ GitLab documentation. Check the
 
 Check the GitLab handbook for the [writing styles guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines).
 
+For help adhering to the guidelines, see [linting](index.md#linting).
+
 ## Files
 
 - [Directory structure](index.md#location-and-naming-documents): place the docs
 in the correct location.
 - [Documentation files](index.md#documentation-files): name the files accordingly.
-- [Markdown](../../user/markdown.md): use the GitLab Flavored Markdown in the
-documentation.
 
-NOTE: **Note:**
+DANGER: **Attention:**
 **Do not** use capital letters, spaces, or special chars in file names,
 branch names, directory names, headings, or in anything that generates a path.
 
@@ -26,65 +26,144 @@ NOTE: **Note:**
 **Do not** create new `README.md` files, name them `index.md` instead. There's
 a test that will fail if it spots a new `README.md` file.
 
-## Text
+### Markdown
+
+The [documentation website](https://docs.gitlab.com) had its markdown engine migrated from [Redcarpet to GitLab Kramdown](https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/108)
+in October, 2018.
+
+The [`gitlab-kramdown`](https://gitlab.com/gitlab-org/gitlab_kramdown)
+gem will support all [GFM markup](../../user/markdown.md) in the future. For now,
+use regular markdown markup, following the rules on this style guide. For a complete
+Kramdown reference, check the [GiLab Markdown Kramdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/).
+Use Kramdown markup wisely: do not overuse its specific markup (e.g., `{:.class}`) as it will not render properly in
+[`/help`](#gitlab-help).
+
+## Content
 
-- 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.
+  [directory](index.md#documentation-directory-structure), linked from its
+  higher-level index, and linked from other related pages.
 - Do not duplicate information.
 - Be brief and clear.
-- Unless there's a logical reason not to, add documents in alphabetical order.
+- Unless there's a logical reason not to, structure the document in alphabetical order
+(headings, tables, and lists).
 - 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").
+some features are also objects (e.g. "GitLab's Merge Requests support X." and "Create a new merge request for Z.").
 
-## Formatting
+## 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 by creating new paragraphs.
+  80-100 characters is the recommended line length.
+- Use sentence case for titles, headings, labels, menu items, and buttons.
+- Jump a line between different markups (e.g., after every paragraph, header, list, etc). Example:
 
-- Use double asterisks (`**`) to mark a word or text in bold (`**bold**`).
-- Use undescore (`_`) for text in italics (`_italic_`).
-- Put an empty line between different markups. For example:
     ```md
     ## Header
 
     Paragraph.
 
-    - List item
-    - List item
+    - List item 1
+    - List item 2
     ```
 
-### Punctuation
+## Emphasis
+
+- Use double asterisks (`**`) to mark a word or text in bold (`**bold**`).
+- Use undescore (`_`) for text in italics (`_italic_`).
+- Use greater than (`>`) for blockquotes.
+
+## Punctuation
+
+Check the general punctuation rules for the GitLab documentation on the table below.
+Check specific punctuation rules for [list items](#list-items) below.
+
+| Rule | Example |
+| ---- | ------- |
+| Always end full sentences with a period. | _For a complete overview, read through this document._|
+| Always add a space after a period when beginning a new sentence | _For a complete overview, check this doc. For other references, check out this guide._ |
+| Do not use double spaces. | --- |
+| Do not use tabs for indentation. Use spaces instead. You can configure your code editor to output spaces instead of tabs when pressing the tab key. | --- |
+| Use serial commas ("Oxford commas") before the final 'and/or' in a list. | _You can create new issues, merge requests, and milestones._ |
+| Always add a space before and after dashes when using it in a sentence (for replacing a comma, for example). | _You should try this - or not._ |
+| Always use lowercase after a colon. | _Related Issues: a way to create a relationship between issues._ |
 
-For punctuation rules, please refer to the [GitLab UX guide](https://design.gitlab.com/content/punctuation/).
+## List items
 
-### Ordered and unordered lists
+- Always start list items with a capital letter.
+- Always leave a blank line before and after a list.
+- Begin a line with spaces (not tabs) to denote a subitem.
+- To nest subitems, indent them with two spaces.
+- To nest code blocks, indent them with four spaces.
+- Only use ordered lists when their items describe a sequence of steps to follow.
 
-- Use dashes (`-`) for unordered lists instead of asterisks (`*`).
-- Use the number one (`1`) for ordered lists.
+**Markup:**
+
+- Use dashes (`- `) for unordered lists instead of asterisks (`* `).
+- Use the number one (`1`) for each item in an ordered list.
+When rendered, the list items will appear with sequential numbering.
+
+**Punctuation:**
+
+- Do not add commas (`,`) or semicolons (`;`) to the end of a list item.
+- Only add periods to the end of a list item if the item consists of a complete sentence. The [definition of full sentence](https://www2.le.ac.uk/offices/ld/resources/writing/grammar/grammar-guides/sentence) is: _"a complete sentence always contains a verb, expresses a complete idea, and makes sense standing alone"_.
+- Be consistent throughout the list: if the majority of the items do not end in a period, do not end any of the items in a period, even if they consist of a complete sentence. The opposite is also valid: if the majority of the items end with a period, end all with a period.
 - Separate list items from explanatory text with a colon (`:`). For example:
+
     ```md
     The list is as follows:
 
-    - First item: This explains the first item.
-    - Second item: This explains the second item.
+    - First item: this explains the first item.
+    - Second item: this explains the second item.
     ```
-- For further guidance on punctuation in bullet lists, please refer to the [GitLab UX guide](https://design.gitlab.com/content/punctuation/).
+
+**Examples:**
+
+Do:
+
+- First list item
+- Second list item
+- Third list item
+
+Don't:
+
+- First list item
+- Second list item
+- Third list item.
+
+Do:
+
+- Let's say this is a complete sentence.
+- Let's say this is also a complete sentence.
+- Not a complete sentence.
+
+Don't:
+
+- Let's say this is a complete sentence.
+- Let's say this is also a complete sentence.
+- Not a complete sentence
+
+## Quotes
+
+Valid for markdown content only, not for frontmatter entries:
+
+- Standard quotes: double quotes (`"`). Example: "This is wrapped in double quotes".
+- Quote within a quote: double quotes (`"`) wrap single quotes (`'`). Example: "I am 'quoting' something within a quote".
+
+For other punctuation rules, 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>`.
-- Start with an h2 (`##`), and respect the order h2 > h3 > h4 > h5 > h6.
-  Never skip the hierarchy level, such as h2 > h4
+- Start with an `h2` (`##`), and respect the order `h2` > `h3` > `h4` > `h5` > `h6`.
+  Never skip the hierarchy level, such as `h2` > `h4`
 - 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
@@ -94,21 +173,19 @@ For punctuation rules, please refer to the [GitLab UX guide](https://design.gitl
 - 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`.
+  grammatically and syntactically correct. Mention an [assigned technical writer (TW)](https://about.gitlab.com/handbook/product/categories/)
+  for review.
   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.
+- Do not use links in headings.
+- Add the corresponding [product badge](#product-badges) according to the tier the feature belongs.
 
 ## 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.
+- Use inline link markdown markup `[Text](https://example.com)`.
+  It's easier to read, review, and maintain. **Do not** use `[Text][identifier]`.
 - 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`.
@@ -126,11 +203,12 @@ For punctuation rules, please refer to the [GitLab UX guide](https://design.gitl
 
 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
+- Use bold text for navigation items and the char "greater than" (`>`) 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.
+needs to expand the tab to find the settings you're referring to (e.g., `Navigate to your project's **Settings > CI/CD** and expand **General pipelines**`).
 
 ## Images
 
@@ -139,7 +217,7 @@ needs to expand the tab to find the settings you're referring to.
   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`.
-- Images should have a specific, non-generic name that will differentiate them.
+- Images should have a specific, non-generic name that will differentiate and describe them properly.
 - Keep all file names in lower case.
 - Consider using PNG images instead of JPEG.
 - Compress all images with <https://tinypng.com/> or similar tool.
@@ -162,13 +240,39 @@ Inside the document:
 - If a heading is placed right after an image, always add three dashes (`---`)
   between the image and the heading.
 
+## Code blocks
+
+- Always wrap code added to a sentence in inline code blocks (``` ` ```).
+E.g., `.gitlab-ci.yml`, `git add .`, `CODEOWNERS`, `only: master`.
+File names, commands, entries, and anything that refers to code should be added to code blocks.
+To make things easier for the user, always add a full code block for things that can be
+useful to copy and paste, as they can easily do it with the button on code blocks.
+- For regular code blocks, always use a highlighting class corresponding to the
+language for better readability. Examples:
+
+      ```md
+       ```ruby
+       Ruby code
+       ```
+
+       ```js
+       JavaScript code
+       ```
+
+       ```md
+       Markdown code
+       ```
+      ```
+
+- For a complete reference on code blocks, check the [Kramdown guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/#code-blocks).
+
 ## 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._
+lists, headers, etc will not render correctly. For multiple lines, use blockquotes instead._
 
 ### Note
 
@@ -232,6 +336,31 @@ which renders in docs.gitlab.com to:
 
 If the text spans across multiple lines it's OK to split the line.
 
+For multiple paragraphs, use the symbol `>` before every line:
+
+```md
+> This is the first paragraph.
+>
+> This is the second paragraph.
+>
+> - This is a list item
+> - Second item in the list
+>
+> ### This is an `h3`
+```
+
+Which renders to:
+
+> This is the first paragraph.
+>
+> This is the second paragraph.
+>
+> - This is a list item
+> - Second item in the list
+>
+> ### This is an `h3`
+>{:.no_toc}
+
 ## Specific sections and terms
 
 To mention and/or reference specific terms in GitLab, please follow the styles
@@ -251,7 +380,7 @@ below.
   (in that order) that introduced it. The above quote would be then transformed to:
 
     ```md
-    > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/1242) in GitLab 8.3.
+    > [Introduced](<link-to-issue>) in GitLab 8.3.
     ```
 
 - If the feature is only available in GitLab Enterprise Edition, don't forget to mention
@@ -259,10 +388,22 @@ below.
   the feature is available in:
 
     ```md
-    > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/1242)
-    in [GitLab Starter](https://about.gitlab.com/pricing/) 8.3.
+    > [Introduced](<link-to-issue>) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.3.
     ```
 
+#### Early versions of EE
+
+If the feature was created before GitLab 9.2 (before [different EE tiers were introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/1851)):
+
+- Declare it as "Introduced in GitLab Enterprise Edition X.Y".
+- Note which tier the feature is available in.
+
+For example:
+
+```md
+> [Introduced](<link-to-issue>) in GitLab Enterprise Edition 9.0. Available in [GitLab Premium](https://about.gitlab.com/pricing/).
+```
+
 ### Product badges
 
 When a feature is available in EE-only tiers, add the corresponding tier according to the
@@ -276,18 +417,18 @@ feature availability:
 To exclude GitLab.com tiers (when the feature is not available in GitLab.com), add the
 keyword "only":
 
+- For GitLab Core: `**[CORE 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.
+However, 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 that will show the tiers on hover.
 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.
+GitLab.com Free, and all higher tiers.
 
 #### How it works
 
@@ -303,7 +444,7 @@ 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:
 
-```
+```md
 Save the file and [reconfigure GitLab](../../administration/restart_gitlab.md)
 for the changes to take effect.
 ```
@@ -334,8 +475,8 @@ 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.
+1. Settings that touch configuration files in `config/`.
+1. 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
@@ -372,13 +513,13 @@ the style below as a guide:
 
 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
+- 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
+- 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
+- Different highlighting languages are used for each config in the code block
+- The [references](#references) guide is used for reconfigure/restart
 
 ### Fake tokens
 
@@ -389,19 +530,19 @@ low.
 
 You can use the following fake tokens as examples.
 
-|     **Token type**    |           **Token value**         |
-| --------------------- | --------------------------------- |
-| Private user token    | `9koXpg98eAheJpvBs5tK`            |
-| Personal access token | `n671WNGecHugsdEDPsyo`            |
+| **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`            |
+| CI/CD 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
 
@@ -424,16 +565,16 @@ on this document. Further explanation is given below.
 Use the following table headers to describe the methods. Attributes should
 always be in code blocks using backticks (``` ` ```).
 
-```
+```md
 | Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
+|:----------|:-----|:---------|:------------|
 ```
 
 Rendered example:
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `user`  | string | yes | The GitLab username |
+| Attribute | Type   | Required | Description         |
+|:----------|:-------|:---------|:--------------------|
+| `user`    | string | yes      | The GitLab username |
 
 #### cURL commands
 
@@ -445,12 +586,12 @@ Rendered example:
 - Prefer to use examples using the personal access token and don't pass data of
   username and password.
 
-| Methods | Description |
-| ------- | ----------- |
+| 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 |
+| `-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
 
diff --git a/doc/development/documentation/workflow.md b/doc/development/documentation/workflow.md
index 52bc059a925..75ce8640e87 100644
--- a/doc/development/documentation/workflow.md
+++ b/doc/development/documentation/workflow.md
@@ -7,16 +7,16 @@ description: Learn the process of shipping documentation for GitLab.
 At GitLab, developers contribute new or updated documentation along with their code, but product managers and technical writers also have essential roles in the process.
 
 - Product Managers (PMs): in the issue for all new and updated features,
-PMs include specific documentation requirements that the developer who is
-writing or updating the docs must meet, along with feature descriptions
-and use cases. They call out any specific areas where collaborating with
-a technical writer is recommended, and usually act as the first reviewer
-of the docs.
+  PMs include specific documentation requirements that the developer who is
+  writing or updating the docs must meet, along with feature descriptions
+  and use cases. They call out any specific areas where collaborating with
+  a technical writer is recommended, and usually act as the first reviewer
+  of the docs.
 - Developers: author documentation and merge it on time (up to a week after
-the feature freeze).
+  the feature freeze).
 - Technical Writers: review each issue to ensure PM's requirements are complete,
-help developers with any questions throughout the process, and act as the final
-reviewer of all new and updated docs content before it's merged.
+  help developers with any questions throughout the process, and act as the final
+  reviewer of all new and updated docs content before it's merged.
 
 ## Requirements
 
@@ -112,17 +112,17 @@ and the missed-deliverable due date (the 14th of each month) are both respected.
 The developer should add to the feature MR the documentation containing:
 
 - The [documentation blurb](structure.md#documentation-blurb): copy the
-feature name, overview/description, and use cases from the feature issue
+  feature name, overview/description, and use cases from the feature issue
 - Instructions: write how to use the feature, step by step, with no gaps.
 - [Crosslink for discoverability](structure.md#discoverability): link with
-internal docs and external resources (if applicable)
+  internal docs and external resources (if applicable)
 - Index: link the new doc or the new heading from the higher-level index
-for [discoverability](#discoverability)
+  for [discoverability](#discoverability)
 - [Screenshots](styleguide.md#images): when necessary, add screenshots for:
   - Illustrating a step of the process
   - Indicating the location of a navigation menu
 - Label the MR with `Documentation`, `Deliverable`, `docs-P1`, and assign
-the correct milestone
+  the correct milestone
 - Assign the PM for review
 - When done, mention the `@gl\-docsteam` in the MR asking for review
 - **Due date**: feature freeze date and time
@@ -133,10 +133,10 @@ If the docs aren't being shipped within the feature MR:
 
 - Create a new issue mentioning "docs" or "documentation" in the title (use the Documentation issue description template)
 - Label the issue with: `Documentation`, `Deliverable`, `docs-P1`, `<product-label>`
-(product label == CI/CD, Pages, Prometheus, etc)
+  (product label == CI/CD, Pages, Prometheus, etc)
 - Add the correct milestone
 - Create a new MR for shipping the docs changes and follow the same
-process [described above](#documentation-shipped-in-the-feature-mr)
+  process [described above](#documentation-shipped-in-the-feature-mr)
 - Use the MR description template called "Documentation"
 - Add the same labels and milestone as you did for the issue
 - Assign the PM for review
@@ -162,9 +162,9 @@ The **due date** for **merging** `missed-deliverable` MRs is on the
 
 - **Planning**
   - Once an issue contains a Documentation label and the current milestone, a
-technical writer reviews the Product Manager's documentation requirements
+  technical writer reviews the Product Manager's documentation requirements.
   - Once the documentation requirements are approved, the technical writer can
-work with the developer to discuss any documentation questions and plans/outlines, as needed.
+  work with the developer to discuss any documentation questions and plans/outlines, as needed.
 
 - **Review** - A technical writer must review the documentation for:
   - Clarity
@@ -183,4 +183,3 @@ work with the developer to discuss any documentation questions and plans/outline
   - Describe the difference between new features and feature updates
   - Creating a new doc vs updating an existing doc
 -->
-
diff --git a/doc/development/ee_features.md b/doc/development/ee_features.md
index f9e6efa2c30..790b1bf951b 100644
--- a/doc/development/ee_features.md
+++ b/doc/development/ee_features.md
@@ -119,10 +119,20 @@ This also applies to views.
 
 ### EE features based on CE features
 
-For features that build on existing CE features, write a module in the
-`EE` namespace and `prepend` it in the CE class. This makes conflicts
-less likely to happen during CE to EE merges because only one line is
-added to the CE class - the `prepend` line.
+For features that build on existing CE features, write a module in the `EE`
+namespace and `prepend` it in the CE class, on the last line of the file that
+the class resides in. This makes conflicts less likely to happen during CE to EE
+merges because only one line is added to the CE class - the `prepend` line. For
+example, to prepend a module into the `User` class you would use the following
+approach:
+
+```ruby
+class User < ActiveRecord::Base
+  # ... lots of code here ...
+end
+
+User.prepend(EE::User)
+```
 
 Since the module would require an `EE` namespace, the file should also be
 put in an `ee/` sub-directory. For example, we want to extend the user model
@@ -171,7 +181,7 @@ There are a few gotchas with it:
       class Base
         def execute
           return unless enabled?
-  
+
           # ...
           # ...
         end
@@ -185,12 +195,12 @@ There are a few gotchas with it:
       class Base
         def execute
           return unless enabled?
-  
+
           do_something
         end
-  
+
         private
-  
+
         def do_something
           # ...
           # ...
@@ -204,14 +214,14 @@ There are a few gotchas with it:
     ```ruby
       module EE::Base
         extend ::Gitlab::Utils::Override
-  
+
         override :do_something
         def do_something
           # Follow the above pattern to call super and extend it
         end
       end
     ```
-  
+
     This would require updating CE first, or make sure this is back ported to CE.
 
 When prepending, place them in the `ee/` specific sub-directory, and
@@ -231,7 +241,6 @@ the existing file:
 
 ```ruby
 class ApplicationController < ActionController::Base
-  prepend EE::ApplicationController
   # ...
 
   def after_sign_out_path_for(resource)
@@ -240,6 +249,8 @@ class ApplicationController < ActionController::Base
 
   # ...
 end
+
+ApplicationController.prepend(EE::ApplicationController)
 ```
 
 And create a new file in the `ee/` sub-directory with the altered
@@ -332,6 +343,21 @@ full implementation details.
 [ce-mr-full-private]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12373
 [ee-mr-full-private]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/2199
 
+### Code in `config/routes`
+
+When we add `draw :admin` in `config/routes.rb`, the application will try to
+load the file located in `config/routes/admin.rb`, and also try to load the
+file located in `ee/config/routes/admin.rb`.
+
+In EE, it should at least load one file, at most two files. If it cannot find
+any files, an error will be raised. In CE, since we don't know if there will
+be an EE route, it will not raise any errors even if it cannot find anything.
+
+This means if we want to extend a particular CE route file, just add the same
+file located in `ee/config/routes`. If we want to add an EE only route, we
+could still put `draw :ee_only` in both CE and EE, and add
+`ee/config/routes/ee_only.rb` in EE, similar to `render_if_exists`.
+
 ### Code in `app/controllers/`
 
 In controllers, the most common type of conflict is with `before_action` that
@@ -393,7 +419,7 @@ view. For instance the approval code in the project's settings page.
 **Mitigations**
 
 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
+avoids conflicts with big chunks of HAML code that are not fun to
 resolve when you add the indentation to the equation.
 
 EE-specific views should be placed in `ee/app/views/`, using extra
@@ -485,7 +511,7 @@ module EE
         params do
           requires :id, type: String, desc: 'The ID of a project'
         end
-        resource :projects, requirements: ::API::API::PROJECT_ENDPOINT_REQUIREMENTS do
+        resource :projects, requirements: ::API::API::NAMESPACE_OR_PROJECT_REQUIREMENTS do
           # ...
         end
       end
@@ -518,8 +544,6 @@ module API
       end
     end
 
-    prepend EE::API::MergeRequests
-
     params :optional_params do
       # CE specific params go here...
 
@@ -527,6 +551,8 @@ module API
     end
   end
 end
+
+API::MergeRequests.prepend(EE::API::MergeRequests)
 ```
 
 And then we could override it in EE module:
@@ -567,10 +593,10 @@ module API
         authorize_read_builds!
       end
     end
-
-    prepend EE::API::JobArtifacts
   end
 end
+
+API::JobArtifacts.prepend(EE::API::JobArtifacts)
 ```
 
 And then we can follow regular object-oriented practices to override it:
@@ -611,8 +637,6 @@ module API
       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])
 
@@ -624,6 +648,8 @@ module API
     end
   end
 end
+
+API::MergeRequests.prepend(EE::API::MergeRequests)
 ```
 
 Note that `update_merge_request_ee` doesn't do anything in CE, but
@@ -661,27 +687,37 @@ or not we really need to extend it from EE. For now we're not using it much.
 
 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.
+different blocks. In order to overcome this, we need to move the data to a class
+method that resides in a separate module or class. This allows us to extend that
+module or class before its data is used, without having to place a `prepend` in
+the middle of CE code.
 
 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:
+least argument. We would approach this as follows:
 
 ```ruby
+# api/merge_requests/parameters.rb
 module API
   class MergeRequests < Grape::API
-    def self.update_params_at_least_one_of
-      %i[
-        assignee_id
-        description
-      ]
+    module Parameters
+      def self.update_params_at_least_one_of
+        %i[
+          assignee_id
+          description
+        ]
+      end
     end
+  end
+end
 
-    prepend EE::API::MergeRequests
+API::MergeRequests::Parameters.prepend(EE::API::MergeRequests::Parameters)
 
+# api/merge_requests.rb
+module API
+  class MergeRequests < Grape::API
     params do
-      at_least_one_of(*::API::MergeRequests.update_params_at_least_one_of)
+      at_least_one_of(*Parameters.update_params_at_least_one_of)
     end
   end
 end
@@ -693,16 +729,18 @@ And then we could easily extend that argument in the EE class method:
 module EE
   module API
     module MergeRequests
-      extend ActiveSupport::Concern
+      module Parameters
+        extend ActiveSupport::Concern
 
-      class_methods do
-        extend ::Gitlab::Utils::Override
+        class_methods do
+          extend ::Gitlab::Utils::Override
 
-        override :update_params_at_least_one_of
-        def update_params_at_least_one_of
-          super.push(*%i[
-            squash
-          ])
+          override :update_params_at_least_one_of
+          def update_params_at_least_one_of
+            super.push(*%i[
+              squash
+            ])
+          end
         end
       end
     end
@@ -713,6 +751,78 @@ end
 It could be annoying if we need this for a lot of routes, but it might be the
 simplest solution right now.
 
+This approach can also be used when models define validations that depend on
+class methods. For example:
+
+```ruby
+# app/models/identity.rb
+class Identity < ActiveRecord::Base
+  def self.uniqueness_scope
+    [:provider]
+  end
+
+  prepend EE::Identity
+
+  validates :extern_uid,
+    allow_blank: true,
+    uniqueness: { scope: uniqueness_scope, case_sensitive: false }
+end
+
+# ee/app/models/ee/identity.rb
+module EE
+  module Identity
+    extend ActiveSupport::Concern
+
+    class_methods do
+      extend ::Gitlab::Utils::Override
+
+      def uniqueness_scope
+        [*super, :saml_provider_id]
+      end
+    end
+  end
+end
+```
+
+Instead of taking this approach, we would refactor our code into the following:
+
+```ruby
+# ee/app/models/ee/identity/uniqueness_scopes.rb
+module EE
+  module Identity
+    module UniquenessScopes
+      extend ActiveSupport::Concern
+
+      class_methods do
+        extend ::Gitlab::Utils::Override
+
+        def uniqueness_scope
+          [*super, :saml_provider_id]
+        end
+      end
+    end
+  end
+end
+
+# app/models/identity/uniqueness_scopes.rb
+class Identity < ActiveRecord::Base
+  module UniquenessScopes
+    def self.uniqueness_scope
+      [:provider]
+    end
+  end
+end
+
+Identity::UniquenessScopes.prepend(EE::Identity::UniquenessScopes)
+
+# app/models/identity.rb
+class Identity < ActiveRecord::Base
+  validates :extern_uid,
+    allow_blank: true,
+    uniqueness: { scope: Identity::UniquenessScopes.scopes, case_sensitive: false }
+end
+```
+
 ### Code in `spec/`
 
 When you're testing EE-only features, avoid adding examples to the
diff --git a/doc/development/fe_guide/components.md b/doc/development/fe_guide/components.md
index ee0c2d534ff..0e9126ee667 100644
--- a/doc/development/fe_guide/components.md
+++ b/doc/development/fe_guide/components.md
@@ -6,7 +6,7 @@
 
 ## Dropdowns
 
-See also the [corresponding UX guide](../ux_guide/components.md#dropdowns).
+See also the [corresponding UX guide](https://design.gitlab.com/#/components/dropdowns).
 
 ### How to style a bootstrap dropdown
 1. Use the HTML structure provided by the [docs][bootstrap-dropdowns]
@@ -40,7 +40,7 @@ See also the [corresponding UX guide](../ux_guide/components.md#dropdowns).
 
 ## Modals
 
-See also the [corresponding UX guide](../ux_guide/components.md#modals).
+See also the [corresponding UX guide](https://design.gitlab.com/#/components/modals).
 
 We have a reusable Vue component for modals: [vue_shared/components/gl_modal.vue](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/assets/javascripts/vue_shared/components/gl_modal.vue)
 
diff --git a/doc/development/fe_guide/droplab/droplab.md b/doc/development/fe_guide/droplab/droplab.md
index 112ff3419d9..ce96a9fc8ae 100644
--- a/doc/development/fe_guide/droplab/droplab.md
+++ b/doc/development/fe_guide/droplab/droplab.md
@@ -123,7 +123,7 @@ droplab.init().addData([{
 ```
 
 Alternatively, you can specify a specific dropdown to add this data to but passing
-the data as the second argument and and the `id` of the trigger element as the first argument.
+the data as the second argument and the `id` of the trigger element as the first argument.
 
 ```html
 <a href="#" data-dropdown-trigger="#list" id="trigger">Toggle</a>
diff --git a/doc/development/fe_guide/graphql.md b/doc/development/fe_guide/graphql.md
new file mode 100644
index 00000000000..f55f01720fd
--- /dev/null
+++ b/doc/development/fe_guide/graphql.md
@@ -0,0 +1,83 @@
+# GraphQL
+
+We use [Apollo] and [Vue Apollo][vue-apollo] for working with GraphQL
+on the frontend.
+
+In order to use GraphQL, you need to enable the `graphql` feature flag,
+read more about [Feature Flags][feature-flags].
+
+## Apollo Client
+
+To save duplicated clients getting created in different apps, we have a
+[default client][defualt-client] that should be used. This setups the
+Apollo client with the correct URL and also sets the CSRF headers.
+
+## GraphQL Queries
+
+To save query compilation at runtime, webpack can directly import `.graphql`
+files. This allows webpack to preprocess the query at compile time instead
+of the client doing compilation of queries.
+
+## Usage in Vue
+
+To use Vue Apollo, import the [Vue Apollo][vue-apollo] plugin as well
+as the default client. This should be created at the same point
+the Vue application is mounted.
+
+```javascript
+import Vue from 'vue';
+import VueApollo from 'vue-apollo';
+import defaultClient from '~/lib/graphql';
+Vue.use(VueApollo);
+
+const apolloProvider = new VueApollo({
+  defaultClient,
+});
+
+new Vue({
+  ...,
+  apolloProvider,
+  ...
+});
+```
+
+Read more about [Vue Apollo][vue-apollo] in the [Vue Apollo documentation][vue-apollo-docs].
+
+### Testing
+
+With [Vue test utils][vue-test-utils] it is easy to quickly test components that
+fetch GraphQL queries. The simplest way is to use `shallowMount` and then set
+the data on the component
+
+```javascript
+it('tests apollo component', () => {
+  const vm = shallowMount(App);
+
+  vm.setData({
+    ...mock data
+  });
+});
+```
+
+## Usage outside of Vue
+
+It is also possible to use GraphQL outside of Vue by directly importing
+and using the default client with queries.
+
+```javascript
+import defaultClient from '~/lib/graphql';
+import query from './query.graphql';
+
+defaultClient.query(query)
+  .then(result => console.log(result));
+```
+
+Read more about the [Apollo] client in the [Apollo documentation][apollo-client-docs].
+
+[Apollo]: https://www.apollographql.com/
+[vue-apollo]: https://github.com/Akryum/vue-apollo/
+[vue-apollo-docs]: https://akryum.github.io/vue-apollo/
+[feature-flags]: ../feature_flags.md
+[default-client]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/assets/javascripts/lib/graphql.js
+[apollo-client-docs]: https://www.apollographql.com/docs/tutorial/client.html
+[vue-test-utils]: https://vue-test-utils.vuejs.org/
diff --git a/doc/development/fe_guide/icons.md b/doc/development/fe_guide/icons.md
index 3d8da6accc1..533e2001300 100644
--- a/doc/development/fe_guide/icons.md
+++ b/doc/development/fe_guide/icons.md
@@ -3,7 +3,7 @@
 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`.
+To upgrade to a new version run `yarn upgrade @gitlab/svgs`.
 
 ## Icons
 
@@ -111,6 +111,6 @@ export default {
 </template>
 ```
 
-[npm]: https://www.npmjs.com/package/@gitlab-org/gitlab-svgs
+[npm]: https://www.npmjs.com/package/@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 11b9a2e6a64..cca3ad6fae6 100644
--- a/doc/development/fe_guide/index.md
+++ b/doc/development/fe_guide/index.md
@@ -54,6 +54,9 @@ Vuex specific design patterns and practices.
 ## [Axios](axios.md)
 Axios specific practices and gotchas.
 
+## [GraphQL](graphql.md)
+How to use GraphQL
+
 ## [Icons and Illustrations](icons.md)
 How we use SVG for our Icons and Illustrations.
 
diff --git a/doc/development/fe_guide/style_guide_js.md b/doc/development/fe_guide/style_guide_js.md
index 656ddd868cd..1e0529262ad 100644
--- a/doc/development/fe_guide/style_guide_js.md
+++ b/doc/development/fe_guide/style_guide_js.md
@@ -1,11 +1,13 @@
 # Style guides and linting
+
 See the relevant style guides for our guidelines and for information on linting:
 
 ## JavaScript
+
 We defer to [Airbnb][airbnb-js-style-guide] on most style-related
 conventions and enforce them with eslint.
 
-See [our current .eslintrc][eslintrc] for specific rules and patterns.
+See [our current .eslintrc](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.eslintrc.yml) for specific rules and patterns.
 
 ### Common
 
@@ -21,10 +23,10 @@ refactor an existing one, you should abide by the eslint rules.
     ```javascript
       // bad
       /* eslint-disable */
- 
+
       // better
       /* eslint-disable some-rule, some-other-rule */
- 
+
       // best
       // nothing :)
     ```
@@ -34,14 +36,14 @@ refactor an existing one, you should abide by the eslint rules.
     ```javascript
       // bad
       /* eslint-disable no-new */
- 
+
       import Foo from 'foo';
- 
+
       new Foo();
- 
+
       // better
       import Foo from 'foo';
- 
+
       // eslint-disable-next-line no-new
       new Foo();
     ```
@@ -58,11 +60,11 @@ followed by any global declarations, then a blank newline prior to any imports o
       /* global Foo */
       /* eslint-disable no-new */
       import Bar from './bar';
- 
+
       // good
       /* eslint-disable no-new */
       /* global Foo */
- 
+
       import Bar from './bar';
     ```
 
@@ -73,7 +75,7 @@ followed by any global declarations, then a blank newline prior to any imports o
     ```javascript
       // bad
       /* globals Flash, Cookies, jQuery */
- 
+
       // good
       /* global Flash */
       /* global Cookies */
@@ -85,7 +87,7 @@ followed by any global declarations, then a blank newline prior to any imports o
     ```javascript
       // bad
       fn(p1, p2, p3, p4) {}
- 
+
       // good
       fn(options) {}
     ```
@@ -191,28 +193,28 @@ Do not use them anymore and feel free to remove them when refactoring legacy cod
     ```javascript
     // bad
     const values = {foo: 1};
- 
+
     function impureFunction(items) {
       const bar = 1;
- 
+
       items.foo = items.a * bar + 2;
- 
+
       return items.a;
     }
- 
+
     const c = impureFunction(values);
- 
+
     // good
     var values = {foo: 1};
- 
+
     function pureFunction (foo) {
       var bar = 1;
- 
+
       foo = foo * bar + 2;
- 
+
       return foo;
     }
- 
+
     var c = pureFunction(values.foo);
     ```
 
@@ -231,10 +233,10 @@ Do not use them anymore and feel free to remove them when refactoring legacy cod
         document.addEventListener('click', this.handleCallback)
       },
       handleCallback() {
-    
+
       }
     }
-    
+
     // Good
     export class Foo {
       constructor() {
@@ -253,12 +255,12 @@ Do not use them anymore and feel free to remove them when refactoring legacy cod
 
     ```javascript
       const users = [ { name: 'Foo' }, { name: 'Bar' } ];
-  
+
       // bad
       users.forEach((user, index) => {
         user.id = index;
       });
-  
+
       // good
       const usersWithId = users.map((user, index) => {
         return Object.assign({}, user, { id: index });
@@ -272,10 +274,10 @@ Do not use them anymore and feel free to remove them when refactoring legacy cod
     ```javascript
       // bad
       +'10' // 10
-  
+
       // good
       Number('10') // 10
-  
+
       // better
       parseInt('10', 10);
     ```
@@ -289,7 +291,7 @@ Do not use them anymore and feel free to remove them when refactoring legacy cod
       <button class="add-user">
         Add User
       </button>
-  
+
       // good
       <button class="js-add-user">
         Add User
@@ -299,10 +301,12 @@ Do not use them anymore and feel free to remove them when refactoring legacy cod
 ### Vue.js
 
 #### `eslint-vue-plugin`
+
 We default to [eslint-vue-plugin][eslint-plugin-vue], with the `plugin:vue/recommended`.
 Please check this [rules][eslint-plugin-vue-rules] for more documentation.
 
 #### Basic Rules
+
 1. The service has it's own file
 1. The store has it's own file
 1. Use a function in the bundle file to instantiate the Vue component:
@@ -314,7 +318,7 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation.
           new Component({})
         }
       }
-  
+
       // good
       document.addEventListener('DOMContentLoaded', () => new Vue({
         el: '#element',
@@ -336,7 +340,7 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation.
           }
         }
       }
-  
+
       // good
       class Store {
         constructor() {
@@ -354,14 +358,14 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation.
     ```javascript
       // bad
       import cardBoard from 'cardBoard.vue'
-  
+
       components: {
         cardBoard,
       };
-  
+
       // good
       import CardBoard from 'cardBoard.vue'
-  
+
       components: {
         CardBoard,
       };
@@ -373,13 +377,13 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation.
     ```javascript
       // bad
       <component class="btn">
-  
+
       // good
       <component css-class="btn">
-  
+
       // bad
       <component myProp="prop" />
-  
+
       // good
       <component my-prop="prop" />
     ```
@@ -387,6 +391,7 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation.
 [#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:
@@ -395,31 +400,31 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation.
           // bad
           <component v-if="bar"
               param="baz" />
-  
+
           <button class="btn">Click me</button>
-  
+
           // good
           <component
             v-if="bar"
             param="baz"
           />
-  
+
           <button class="btn">
             Click me
           </button>
         ```
-  
+
    1. The tag can be inline if there is only one attribute:
 
         ```javascript
           // good
             <component bar="bar" />
-  
+
           // good
             <component
               bar="bar"
               />
-  
+
           // bad
            <component
               bar="bar" />
@@ -434,7 +439,7 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation.
       template: `
         <button :class='style'>Button</button>
       `
-  
+
       // good
       template: `
         <button :class="style">Button</button>
@@ -447,7 +452,7 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation.
     ```javascript
       // bad
       props: ['foo']
-  
+
       // good
       props: {
         foo: {
@@ -467,7 +472,7 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation.
           type: String,
         }
       }
-  
+
       // good
       props: {
         foo: {
@@ -490,7 +495,7 @@ On those a default key should not be provided.
           required: false,
         }
       }
-  
+
       // good
       props: {
         foo: {
@@ -499,7 +504,7 @@ On those a default key should not be provided.
           default: 'bar'
         }
       }
-  
+
       // good
       props: {
         foo: {
@@ -534,7 +539,7 @@ On those a default key should not be provided.
     ```javascript
       // bad
       <component v-on:click="eventHandler"/>
-  
+
       // good
       <component @click="eventHandler"/>
     ```
@@ -544,7 +549,7 @@ On those a default key should not be provided.
     ```javascript
       // bad
       <component v-bind:class="btn"/>
-  
+
       // good
       <component :class="btsn"/>
     ```
@@ -556,7 +561,7 @@ On those a default key should not be provided.
     ```javascript
       // bad
       <component></component>
-  
+
       // good
       <component />
     ```
@@ -650,7 +655,7 @@ Useful links:
         title="Some tooltip text">
         Text
       </span>
-  
+
       // good
       <span
         v-tooltip
@@ -666,10 +671,10 @@ Useful links:
     ```javascript
       // bad
       <span data-original-title="tooltip text">Foo</span>
-  
+
       // good
       <span title="tooltip text">Foo</span>
-  
+
       $('span').tooltip('_fixTitle');
     ```
 
diff --git a/doc/development/fe_guide/style_guide_scss.md b/doc/development/fe_guide/style_guide_scss.md
index 48eb6d0a7d6..b09243598d5 100644
--- a/doc/development/fe_guide/style_guide_scss.md
+++ b/doc/development/fe_guide/style_guide_scss.md
@@ -183,9 +183,11 @@ Don't use ID selectors in CSS.
 ```
 
 ### Variables
+
 Before adding a new variable for a color or a size, guarantee:
-1. There isn't already one
-2. There isn't a similar one we can use instead.
+
+- There isn't already one
+- There isn't a similar one we can use instead.
 
 ## Linting
 
diff --git a/doc/development/fe_guide/vue.md b/doc/development/fe_guide/vue.md
index f6cbd11042c..ccfd465531a 100644
--- a/doc/development/fe_guide/vue.md
+++ b/doc/development/fe_guide/vue.md
@@ -221,6 +221,14 @@ const vm = mountComponent(Component, data);
 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:
 
+## Vue.js Expert Role
+One should apply to be a Vue.js expert by opening an MR when the Merge Request's they create and review show:
+- Deep understanding of Vue and Vuex reactivy
+- Vue and Vuex code are structured according to both official and our guidelines
+- Full understanding of testing a Vue and Vuex application
+- Vuex code follows the [documented pattern](./vuex.md#actions-pattern-request-and-receive-namespaces)
+- Knowledge about the existing Vue and Vuex applications and existing reusable components
+
 
 [vue-docs]: http://vuejs.org/guide/index.html
 [issue-boards]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/app/assets/javascripts/boards
diff --git a/doc/development/fe_guide/vuex.md b/doc/development/fe_guide/vuex.md
index f582f5da323..0f57835fb87 100644
--- a/doc/development/fe_guide/vuex.md
+++ b/doc/development/fe_guide/vuex.md
@@ -114,19 +114,21 @@ 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`
+        - `PUT`: `createSomething`
+        - `POST`: `updateSomething`
+        - `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
@@ -297,12 +299,12 @@ export default {
 
     ```javascript
       // component.vue
-  
+
       // bad
       created() {
         this.$store.commit('mutation');
       }
-  
+
       // good
       created() {
         this.$store.dispatch('action');
diff --git a/doc/development/feature_flags.md b/doc/development/feature_flags.md
index 417298205f5..1019a1fd0e2 100644
--- a/doc/development/feature_flags.md
+++ b/doc/development/feature_flags.md
@@ -33,7 +33,7 @@ You can follow the progress on that [in the issue on our issue tracker](https://
 
 In general, it's better to have a group- or user-based gate, and you should prefer
 it over the use of percentage gates. This would make debugging easier, as you
-filter for example logs and errors based on actors too. Futhermore, this allows
+filter for example logs and errors based on actors too. Furthermore, this allows
 for enabling for the `gitlab-org` group first, while the rest of the users
 aren't impacted.
 
@@ -69,6 +69,37 @@ For more information about rolling out changes using feature flags, refer to the
 [Rolling out changes using feature flags](rolling_out_changes_using_feature_flags.md)
 guide.
 
+### Frontend
+
+For frontend code you can use the method `push_frontend_feature_flag`, which is
+available to all controllers that inherit from `ApplicationController`. Using
+this method you can expose the state of a feature flag as follows:
+
+```ruby
+before_action do
+  push_frontend_feature_flag(:vim_bindings)
+end
+
+def index
+  # ...
+end
+
+def edit
+  # ...
+end
+```
+
+You can then check for the state of the feature flag in JavaScript as follows:
+
+```javascript
+if ( gon.features.vimBindings ) {
+  // ...
+}
+```
+
+The name of the feature flag in JavaScript will always be camelCased, meaning
+that checking for `gon.features.vim_bindings` would not work.
+
 ### Specs
 
 In the test environment `Feature.enabled?` is stubbed to always respond to `true`,
@@ -81,3 +112,8 @@ feature flag. You can stub a feature flag as follows:
 ```ruby
 stub_feature_flags(my_feature_flag: false)
 ```
+
+## Enabling a feature flag
+
+Check how to [roll out changes using feature flags](rolling_out_changes_using_feature_flags.md).
+
diff --git a/doc/development/gitaly.md b/doc/development/gitaly.md
index 4f9ca1920a5..32beafad307 100644
--- a/doc/development/gitaly.md
+++ b/doc/development/gitaly.md
@@ -1,15 +1,11 @@
 # GitLab Developers Guide to Working with Gitaly
 
 [Gitaly](https://gitlab.com/gitlab-org/gitaly) is a high-level Git RPC service used by GitLab CE/EE,
-Workhorse and GitLab-Shell. All Rugged operations in GitLab CE/EE are currently being phased out to
-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.
+Workhorse and GitLab-Shell.
 
 ## Developing new Git features
 
-Starting with Gitlab 10.8, all new Git features should be developed in
+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
@@ -52,57 +48,6 @@ 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).
-
-Each Rugged-to-Gitaly migration goes through a [series of phases](https://gitlab.com/gitlab-org/gitaly/blob/master/doc/MIGRATION_PROCESS.md):
-
-* **Opt-In**: by default the Rugged implementation is used.
-  * Production instances can choose to enable the Gitaly endpoint by enabling the feature flag.
-  * For testing purposes, you may wish to enable all feature flags by default. This can be done by exporting the following
-    environment variable: `GITALY_FEATURE_DEFAULT_ON=1`.
-  * On developer instances (ie, when `Rails.env.development?` is true), the Gitaly endpoint
-    is enabled by default, but can be _disabled_ using feature flags.
-* **Opt-Out**: by default, the Gitaly endpoint is used, but the feature can be explicitly disabled using the feature flag.
-* **Mandatory**: The migration is complete and cannot be disabled. The old codepath is removed.
-
-### Enabling and Disabling Feature
-
-In the Rails console, type:
-
-```ruby
-Feature.enable(:gitaly_feature_name)
-Feature.disable(:gitaly_feature_name)
-```
-
-Where `gitaly_feature_name` is the name of the Gitaly feature. This can be determined by finding the appropriate
-`gitaly_migrate` code block, for example:
-
-```ruby
-gitaly_migrate(:tag_names) do
-...
-end
-```
-
-Since Gitaly features are always prefixed with `gitaly_`, the name of the feature flag in this case would be `gitaly_tag_names`.
-
 ## Gitaly-Related Test Failures
 
 If your test-suite is failing with Gitaly issues, as a first step, try running:
diff --git a/doc/development/github_importer.md b/doc/development/github_importer.md
index 0d558583bb8..863ac049db6 100644
--- a/doc/development/github_importer.md
+++ b/doc/development/github_importer.md
@@ -99,8 +99,8 @@ This worker will wrap up the import process by performing some housekeeping
 
 Advancing stages is done in one of two ways:
 
-1. Scheduling the worker for the next stage directly.
-2. Scheduling a job for `Gitlab::GithubImport::AdvanceStageWorker` which will
+- Scheduling the worker for the next stage directly.
+- Scheduling a job for `Gitlab::GithubImport::AdvanceStageWorker` which will
    advance the stage when all work of the current stage has been completed.
 
 The first approach should only be used by workers that perform all their work in
@@ -131,7 +131,7 @@ our import as failed because of this.
 To prevent this from happening we periodically refresh the expiration time of
 the import process. This works by storing the JID of the import job in the
 database, then refreshing this JID's TTL at various stages throughout the import
-process. This is done by calling `Project#refresh_import_jid_expiration`. By
+process. This is done by calling `ProjectImportState#refresh_jid_expiration`. By
 refreshing this TTL we can ensure our import does not get marked as failed so
 long we're still performing work.
 
@@ -147,7 +147,7 @@ We handle this by doing the following:
 
 1. Once we hit the rate limit all jobs will automatically reschedule themselves
    in such a way that they are not executed until the rate limit has been reset.
-2. We cache the mapping of GitHub users to GitLab users in Redis.
+1. We cache the mapping of GitHub users to GitLab users in Redis.
 
 More information on user caching can be found below.
 
@@ -157,21 +157,21 @@ When mapping GitHub users to GitLab users we need to (in the worst case)
 perform:
 
 1. One API call to get the user's Email address.
-2. Two database queries to see if a corresponding GitLab user exists. One query
+1. Two database queries to see if a corresponding GitLab user exists. One query
    will try to find the user based on the GitHub user ID, while the second query
    is used to find the user using their GitHub Email address.
 
 Because this process is quite expensive we cache the result of these lookups in
 Redis. For every user looked up we store three keys:
 
-1. A Redis key mapping GitHub usernames to their Email addresses.
-2. A Redis key mapping a GitHub Email addresses to a GitLab user ID.
-3. A Redis key mapping a GitHub user ID to GitLab user ID.
+- A Redis key mapping GitHub usernames to their Email addresses.
+- A Redis key mapping a GitHub Email addresses to a GitLab user ID.
+- A Redis key mapping a GitHub user ID to GitLab user ID.
 
 There are two types of lookups we cache:
 
-1. A positive lookup, meaning we found a GitLab user ID.
-2. A negative lookup, meaning we didn't find a GitLab user ID. Caching this
+- A positive lookup, meaning we found a GitLab user ID.
+- A negative lookup, meaning we didn't find a GitLab user ID. Caching this
    prevents us from performing the same work for users that we know don't exist
    in our GitLab database.
 
diff --git a/doc/development/gotchas.md b/doc/development/gotchas.md
index 84dea7ce9aa..a5a34d82bec 100644
--- a/doc/development/gotchas.md
+++ b/doc/development/gotchas.md
@@ -92,7 +92,7 @@ describe API::Labels do
 end
 ```
 
-## Avoid using `allow_any_instance_of` in RSpec
+## Avoid using `expect_any_instance_of` or `allow_any_instance_of` in RSpec
 
 ### Why
 
@@ -102,7 +102,7 @@ end
   error like this:
 
     ```
-    1.1) Failure/Error: allow_any_instance_of(ApplicationSetting).to receive_messages(messages)
+    1.1) Failure/Error: expect_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.
     ```
 
@@ -112,7 +112,7 @@ Instead of writing:
 
 ```ruby
 # Don't do this:
-allow_any_instance_of(Project).to receive(:add_import_job)
+expect_any_instance_of(Project).to receive(:add_import_job)
 ```
 
 We could write:
diff --git a/doc/development/i18n/index.md b/doc/development/i18n/index.md
index 7290a175501..c44690a4c5d 100644
--- a/doc/development/i18n/index.md
+++ b/doc/development/i18n/index.md
@@ -50,3 +50,5 @@ able to proofread and instructions on becoming a proofreader yourself.
 ## Release
 
 Translations are typically included in the next major or minor release.
+
+See [Merging translations from Crowdin](merging_translations.md)
diff --git a/doc/development/i18n/merging_translations.md b/doc/development/i18n/merging_translations.md
new file mode 100644
index 00000000000..d172aa6da21
--- /dev/null
+++ b/doc/development/i18n/merging_translations.md
@@ -0,0 +1,60 @@
+# Merging translations from Crowdin
+
+Crowdin automatically syncs the `gitlab.pot` file presenting newly
+added translations to the community of translators.
+
+At the same time, it creates a merge request to merge all newly added
+& approved translations. Find the [merge reqeust created by
+`gitlab-crowdin-bot`](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests?scope=all&utf8=%E2%9C%93&state=opened&author_username=gitlab-crowdin-bot)
+to see new and merged merge requests. They are created in EE and need
+to be ported to CE manually.
+
+## Validation
+
+By default Crowdin commits translations with `[skip ci]` in the commit
+message. This is done to avoid a bunch of pipelines being run. Before
+merging translations, make sure to trigger a pipeline to validate
+translations, we have static analysis validating things Crowdin
+doesn't do. Create a [new pipeline](https://gitlab.com/gitlab-org/gitlab-ee/pipelines/new) for the
+`master-i18n` branch.
+
+If there are validation errors, the easiest solution is to disapprove
+the offending string in Crowdin, leaving a comment with what is
+required to fix the offense. There is an
+[issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/49208)
+suggesting to automate this process. Disapproving will exclude the
+invalid translation, the merge request will be updated within a few
+minutes.
+
+It might be handy to pause the integration on the Crowdin side for a
+little while so translations don't keep coming. This can be done by
+clicking `Pause sync` on the [Crowdin integration settings
+page](https://translate.gitlab.com/project/gitlab-ee/settings#integration).
+
+When all failures are resolved, the translations need to be double
+checked once more [as discussed in this
+issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/37850).
+
+## Merging translations
+
+When all translations are found good and pipelines pass the
+translations can be merged into the master branch. After that is done,
+create a new merge request cherry-picking the translations from EE to
+CE. When merging the translations, make sure to check the `Remove
+source branch` checkbox, so Crowdin recreates the `master-i18n` from
+master after the new translation was merged.
+
+We are discussing automating this entire process
+[here](https://gitlab.com/gitlab-org/gitlab-ce/issues/39309).
+
+## Recreate the merge request
+
+Crowdin creates a new merge request as soon as the old one is closed
+or merged. But it won't recreate the `master-i18n` branch every
+time. To force Crowdin to recreate the branch, close any [open merge
+request](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests?scope=all&utf8=%E2%9C%93&state=opened&author_username=gitlab-crowdin-bot)
+and delete the
+[`master-18n`](https://gitlab.com/gitlab-org/gitlab-ee/branches/all?utf8=%E2%9C%93&search=master-i18n).
+
+This might be needed when the merge request contains failures that
+have been fixed on master.
diff --git a/doc/development/i18n/proofreader.md b/doc/development/i18n/proofreader.md
index 6e57ffbae27..fd4df64999b 100644
--- a/doc/development/i18n/proofreader.md
+++ b/doc/development/i18n/proofreader.md
@@ -5,7 +5,14 @@ are very appreciative of the work done by translators and proofreaders!
 
 ## Proofreaders
 
+- Albanian
+  - Proofreaders needed.
+- Arabic
+  - Proofreaders needed.
 - Bulgarian
+  - Lyubomir Vasilev - [Crowdin](https://crowdin.com/profile/lyubomirv)
+- Catalan
+  - Proofreaders needed.
 - Chinese Simplified
   - Huang Tao - [GitLab](https://gitlab.com/htve), [Crowdin](https://crowdin.com/profile/htve)
 - Chinese Traditional
@@ -14,14 +21,31 @@ are very appreciative of the work done by translators and proofreaders!
   - Yi-Jyun Pan - [GitLab](https://gitlab.com/pan93412), [Crowdin](https://crowdin.com/profile/pan93412)
 - Chinese Traditional, Hong Kong
   - Huang Tao - [GitLab](https://gitlab.com/htve), [Crowdin](https://crowdin.com/profile/htve)
+- Czech
+  - Proofreaders needed.
+- Danish
+  - Proofreaders needed.
 - Dutch
-  -  Emily Hendle - [GitLab](https://gitlab.com/pundachan), [Crowdin](https://crowdin.com/profile/pandachan)
+  - Emily Hendle - [GitLab](https://gitlab.com/pundachan), [Crowdin](https://crowdin.com/profile/pandachan)
 - Esperanto
+- Lyubomir Vasilev - [Crowdin](https://crowdin.com/profile/lyubomirv)
+- Estonian
+  - Proofreaders needed.
+- Filipino
+  - Proofreaders needed.
 - French
   - Davy Defaud - [GitLab](https://gitlab.com/DevDef), [Crowdin](https://crowdin.com/profile/DevDef)
+- Galician
+  - Antón Méixome - [Crowdin](https://crowdin.com/profile/meixome)
+  - Pedro Garcia - [GitLab](https://gitlab.com/pedgarrod), [Crowdin](https://crowdin.com/profile/breaking_pitt)
 - German
+  - Michael Hahnle - [GitLab](https://gitlab.com/mhah), [Crowdin](https://crowdin.com/profile/mhah)
+- Greek
+  - Proofreaders needed.
 - Hebrew
   - Yaron Shahrabani - [GitLab](https://gitlab.com/yarons), [Crowdin](https://crowdin.com/profile/YaronSh)
+- Hungarian
+  - Proofreaders needed.
 - Indonesian
   - Ahmad Naufal Mukhtar - [GitLab](https://gitlab.com/anaufalm), [Crowdin](https://crowdin.com/profile/anaufalm)
 - Italian
@@ -32,18 +56,39 @@ are very appreciative of the work done by translators and proofreaders!
 - 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)
+  - Ji Hun Oh - [GitLab](https://gitlab.com/Baw-Appie), [Crowdin](https://crowdin.com/profile/BawAppie)
+- Mongolian
+  - Proofreaders needed.
+- Norwegian Bokmal
+  - Proofreaders needed.
 - Polish
   - Filip Mech - [GitLab](https://gitlab.com/mehenz), [Crowdin](https://crowdin.com/profile/mehenz)
+- Portuguese
+  - Proofreaders needed.
 - 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)
+- Romanian
+  - Proofreaders needed.
 - 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)
+  - NickVolynkin - [Crowdin](https://crowdin.com/profile/NickVolynkin)
+- Serbian (Cyrillic)
+  - Proofreaders needed.
+- Serbian (Latin)
+  - Proofreaders needed.
+- Slovak
+  - Proofreaders needed.
 - Spanish
+  - Pedro Garcia - [GitLab](https://gitlab.com/pedgarrod), [Crowdin](https://crowdin.com/profile/breaking_pitt)
+- Turkish
+  - Proofreaders needed.
 - Ukrainian
   - Volodymyr Sobotovych - [GitLab](https://gitlab.com/wheleph), [Crowdin](https://crowdin.com/profile/wheleph)
   - Andrew Vityuk - [GitLab](https://gitlab.com/3_1_3_u), [Crowdin](https://crowdin.com/profile/andruwa13)
+- Welsh
+  - Proofreaders needed.
 
 ## Become a proofreader
 
@@ -75,6 +120,8 @@ are very appreciative of the work done by translators and proofreaders!
     have previously translated.
 
 1. Your request to become a proofreader will be considered on the merits of
-   your previous translations.
+   your previous translations by [GitLab team members](https://about.gitlab.com/team/)
+   or [Core team members](https://about.gitlab.com/core-team/) who are fluent in
+   the language or current proofreaders.
 
 [proofreader-src]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/development/i18n/proofreader.md
diff --git a/doc/development/instrumentation.md b/doc/development/instrumentation.md
index a14c0752366..bef166f2aec 100644
--- a/doc/development/instrumentation.md
+++ b/doc/development/instrumentation.md
@@ -69,7 +69,7 @@ The easiest way to check if a method has been instrumented is to check its
 source location. For example:
 
 ```ruby
-method = Rugged::TagCollection.instance_method(:[])
+method = Banzai::Renderer.method(:render)
 
 method.source_location
 ```
@@ -82,7 +82,7 @@ method (along with its source location), this is easier than running the above
 Ruby code. In case of the above snippet you'd run the following:
 
 ```
-$ Rugged::TagCollection#[]
+$ Banzai::Renderer.render
 ```
 
 This will print out something along the lines of:
@@ -117,11 +117,11 @@ The block is executed and the execution time is stored as a set of fields in the
 currently running transaction. If no transaction is present the block is yielded
 without measuring anything.
 
-3 values are measured for a block:
+Three values are measured for a block:
 
-1. The real time elapsed, stored in NAME_real_time.
-2. The CPU time elapsed, stored in NAME_cpu_time.
-3. The call count, stored in NAME_call_count.
+- The real time elapsed, stored in NAME_real_time.
+- The CPU time elapsed, stored in NAME_cpu_time.
+- The call count, stored in NAME_call_count.
 
 Both the real and CPU timings are measured in milliseconds.
 
diff --git a/doc/development/logging.md b/doc/development/logging.md
new file mode 100644
index 00000000000..5c1d96b9e0c
--- /dev/null
+++ b/doc/development/logging.md
@@ -0,0 +1,144 @@
+# GitLab Developers Guide to Logging
+
+[GitLab Logs](../administration/logs.md) play a critical role for both
+administrators and GitLab team members to diagnose problems in the field.
+
+## Don't use `Rails.logger`
+
+Currently `Rails.logger` calls all get saved into `production.log`, which contains
+a mix of Rails' logs and other calls developers have inserted in the code base.
+For example:
+
+```
+Started GET "/gitlabhq/yaml_db/tree/master" for 168.111.56.1 at 2015-02-12 19:34:53 +0200
+Processing by Projects::TreeController#show as HTML
+  Parameters: {"project_id"=>"gitlabhq/yaml_db", "id"=>"master"}
+
+  ...
+
+  Namespaces"."created_at" DESC, "namespaces"."id" DESC LIMIT 1 [["id", 26]]
+  CACHE (0.0ms) SELECT  "members".* FROM "members"  WHERE "members"."source_type" = 'Project' AND "members"."type" IN ('ProjectMember') AND "members"."source_id" = $1 AND "members"."source_type" = $2 AND "members"."user_id" = 1  ORDER BY "members"."created_at" DESC, "members"."id" DESC LIMIT 1  [["source_id", 18], ["source_type", "Project"]]
+  CACHE (0.0ms) SELECT  "members".* FROM "members"  WHERE "members"."source_type" = 'Project' AND "members".
+  (1.4ms) SELECT COUNT(*) FROM "merge_requests"  WHERE "merge_requests"."target_project_id" = $1 AND ("merge_requests"."state" IN ('opened','reopened')) [["target_project_id", 18]]
+  Rendered layouts/nav/_project.html.haml (28.0ms)
+  Rendered layouts/_collapse_button.html.haml (0.2ms)
+  Rendered layouts/_flash.html.haml (0.1ms)
+  Rendered layouts/_page.html.haml (32.9ms)
+Completed 200 OK in 166ms (Views: 117.4ms | ActiveRecord: 27.2ms)
+```
+
+These logs suffer from a number of problems:
+
+1. They often lack timestamps or other contextual information (e.g. project ID, user)
+2. They may span multiple lines, which make them hard to find via Elasticsearch.
+3. They lack a common structure, which make them hard to parse by log
+forwarders, such as Logstash or Fluentd. This also makes them hard to
+search.
+
+Note that currently on GitLab.com, any messages in `production.log` will
+NOT get indexed by Elasticsearch due to the sheer volume and noise. They
+do end up in Google Stackdriver, but it is still harder to search for
+logs there. See the [GitLab.com logging
+documentation](https://gitlab.com/gitlab-com/runbooks/blob/master/howto/logging.md)
+for more details.
+
+## Use structured (JSON) logging
+
+Structured logging solves these problems. Consider the example from an API request:
+
+```json
+{"time":"2018-10-29T12:49:42.123Z","severity":"INFO","duration":709.08,"db":14.59,"view":694.49,"status":200,"method":"GET","path":"/api/v4/projects","params":[{"key":"action","value":"git-upload-pack"},{"key":"changes","value":"_any"},{"key":"key_id","value":"secret"},{"key":"secret_token","value":"[FILTERED]"}],"host":"localhost","ip":"::1","ua":"Ruby","route":"/api/:version/projects","user_id":1,"username":"root","queue_duration":100.31,"gitaly_calls":30}
+```
+
+In a single line, we've included all the information that a user needs
+to understand what happened: the timestamp, HTTP method and path, user
+ID, etc.
+
+### How to use JSON logging
+
+Suppose you want to log the events that happen in a project
+importer. You want to log issues created, merge requests, etc. as the
+importer progresses. Here's what to do:
+
+1. Look at [the list of GitLab Logs](../administration/logs.md) to see
+if your log message might belong with one of the existing log files.
+1. If there isn't a good place, consider creating a new filename, but
+check with a maintainer if it makes sense to do so. A log file should
+make it easy for people to search pertinent logs in one place. For
+example, `geo.log` contains all logs pertaining to GitLab Geo.
+To create a new file:
+    1. Choose a filename (e.g. `importer_json.log`).
+    1. Create a new subclass of `Gitlab::JsonLogger`:
+
+        ```ruby
+        module Gitlab
+          module Import
+            class Logger < ::Gitlab::JsonLogger
+              def self.file_name_noext
+                'importer'
+              end
+            end
+           end
+        end
+        ```
+
+    1. In your class where you want to log, you might initialize the logger as an instance variable:
+
+        ```ruby
+        attr_accessor :logger
+
+        def initialize
+          @logger = Gitlab::Import::Logger.build
+        end
+        ```
+
+        Note that it's useful to memoize this because creating a new logger
+        each time you log will open a file, adding unnecessary overhead.
+
+1. Now insert log messages into your code. When adding logs,
+   make sure to include all the context as key-value pairs:
+
+    ```ruby
+    # BAD
+    logger.info("Unable to create project #{project.id}")
+    ```
+
+    ```ruby
+    # GOOD
+    logger.info(message: "Unable to create project", project_id: project.id)
+    ```
+
+1. Be sure to create a common base structure of your log messages. For example,
+   all messages might have `current_user_id` and `project_id` to make it easier
+   to search for activities by user for a given time.
+
+1. Do NOT mix and match types. Elasticsearch won't be able to index your
+   logs properly if you [mix integer and string
+   types](https://www.elastic.co/guide/en/elasticsearch/guide/current/mapping.html#_avoiding_type_gotchas):
+
+    ```ruby
+    # BAD
+    logger.info(message: "Import error", error: 1)
+    logger.info(message: "Import error", error: "I/O failure")
+    ```
+
+    ```ruby
+    # GOOD
+    logger.info(message: "Import error", error_code: 1, error: "I/O failure")
+    ```
+
+## Additional steps with new log files
+
+1. Consider log retention settings. By default, Omnibus will rotate any
+logs in `/var/log/gitlab/gitlab-rails/*.log` every hour and [keep at
+most 30 compressed files](https://docs.gitlab.com/omnibus/settings/logs.html#logrotate).
+On GitLab.com, that setting is only 6 compressed files. These settings should suffice
+for most users, but you may need to tweak them in [omnibus-gitlab](https://gitlab.com/gitlab-org/omnibus-gitlab).
+
+1. If you add a new file, submit an issue to the [production
+tracker](https://gitlab.com/gitlab-com/gl-infra/production/issues) or
+a merge request to the [gitlab_fluentd](https://gitlab.com/gitlab-cookbooks/gitlab_fluentd)
+project. See [this example](https://gitlab.com/gitlab-cookbooks/gitlab_fluentd/merge_requests/51/diffs).
+
+1. Be sure to update the [GitLab CE/EE documentation](../administration/logs.md) and the [GitLab.com
+runbooks](https://gitlab.com/gitlab-com/runbooks/blob/master/howto/logging.md).
diff --git a/doc/development/merge_request_performance_guidelines.md b/doc/development/merge_request_performance_guidelines.md
index 12badbe39b2..ee01c89e0ed 100644
--- a/doc/development/merge_request_performance_guidelines.md
+++ b/doc/development/merge_request_performance_guidelines.md
@@ -168,6 +168,7 @@ user objects for every username we can remove the need for running the same
 query for every mention of `@alice`.
 
 Caching data per transaction can be done using
-[RequestStore](https://github.com/steveklabnik/request_store). Caching data in
-Redis can be done using [Rails' caching
+[RequestStore](https://github.com/steveklabnik/request_store) (use
+`Gitlab::SafeRequestStore` to avoid having to remember to check
+`RequestStore.active?`). Caching data in Redis can be done using [Rails' caching
 system](http://guides.rubyonrails.org/caching_with_rails.html).
diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md
index 6f31e5b82e5..a99267bfbba 100644
--- a/doc/development/migration_style_guide.md
+++ b/doc/development/migration_style_guide.md
@@ -134,9 +134,9 @@ should be more than enough.
 When removing an index make sure to use the method `remove_concurrent_index` instead
 of the regular `remove_index` method. The `remove_concurrent_index` method
 automatically drops concurrent indexes when using PostgreSQL, removing the
-need for downtime. To use this method you must disable transactions by calling
-the method `disable_ddl_transaction!` in the body of your migration class like
-so:
+need for downtime. To use this method you must disable single-transaction mode
+by calling the method `disable_ddl_transaction!` in the body of your migration
+class like so:
 
 ```ruby
 class MyMigration < ActiveRecord::Migration
@@ -187,12 +187,7 @@ end
 When adding a foreign-key constraint to either an existing or new
 column remember to also add a index on the column.
 
-This is _required_ if the foreign-key constraint specifies
-`ON DELETE CASCADE` or `ON DELETE SET NULL` behavior. On a cascading
-delete, the [corresponding record needs to be retrieved using an
-index](https://www.cybertec-postgresql.com/en/postgresql-indexes-and-foreign-keys/)
-(otherwise, we'd need to scan the whole table) for subsequent update or
-deletion.
+This is _required_ for all foreign-keys.
 
 Here's an example where we add a new column with a foreign key
 constraint. Note it includes `index: true` to create an index for it.
diff --git a/doc/development/module_with_instance_variables.md b/doc/development/module_with_instance_variables.md
index 48a1b7f847e..7bdfa04fc57 100644
--- a/doc/development/module_with_instance_variables.md
+++ b/doc/development/module_with_instance_variables.md
@@ -60,7 +60,7 @@ as long as it's contained in the same module; that is, no other modules or
 objects are touching them, then it would be an acceptable use.
 
 We especially allow the case where a single instance variable is used with
-`||=` to setup the value. This would look like:
+`||=` to set up the value. This would look like:
 
 ``` ruby
 module M
diff --git a/doc/development/new_fe_guide/development/performance.md b/doc/development/new_fe_guide/development/performance.md
index 244dfb3756f..5ccd5357314 100644
--- a/doc/development/new_fe_guide/development/performance.md
+++ b/doc/development/new_fe_guide/development/performance.md
@@ -2,7 +2,7 @@
 
 ## Monitoring
 
-We have a performance dashboard available in one of our [grafana instances](https://performance.gprd.gitlab.com/dashboard/db/sitespeed-page-summary?orgId=1). This dashboard automatically aggregates metric data from [sitespeed.io](https://sitespeed.io) every 6 hours. These changes are displayed after a set number of pages are aggregated.
+We have a performance dashboard available in one of our [grafana instances](https://dashboards.gitlab.net/d/1EBTz3Dmz/sitespeed-page-summary?orgId=1). This dashboard automatically aggregates metric data from [sitespeed.io](https://sitespeed.io) every 6 hours. These changes are displayed after a set number of pages are aggregated.
 
 These pages can be found inside a text file in the gitlab-build-images [repository](https://gitlab.com/gitlab-org/gitlab-build-images) called [gitlab.txt](https://gitlab.com/gitlab-org/gitlab-build-images/blob/master/scripts/gitlab.txt)
 Any frontend engineer can contribute to this dashboard. They can contribute by adding or removing urls of pages from this text file. Please have a [frontend monitoring expert](https://about.gitlab.com/team) review your changes before assigning to a maintainer of the `gitlab-build-images` project. The changes will go live on the next scheduled run after the changes are merged into `master`.
diff --git a/doc/development/new_fe_guide/development/testing.md b/doc/development/new_fe_guide/development/testing.md
index a9223ac6b0f..082acbedcd2 100644
--- a/doc/development/new_fe_guide/development/testing.md
+++ b/doc/development/new_fe_guide/development/testing.md
@@ -1,30 +1,247 @@
 # Overview of Frontend Testing
 
-## Types of tests in our codebase
+Tests relevant for frontend development can be found at two places:
+
+- `spec/javascripts/` which are run by Karma and contain
+  - [frontend unit tests](#frontend-unit-tests)
+  - [frontend component tests](#frontend-component-tests)
+  - [frontend integration tests](#frontend-integration-tests)
+- `spec/features/` which are run by RSpec and contain
+  - [feature tests](#feature-tests)
+
+In addition there were feature tests in `features/` run by Spinach in the past.
+These have been removed from our codebase in May 2018 ([#23036](https://gitlab.com/gitlab-org/gitlab-ce/issues/23036)).
+
+See also:
 
-* **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`)
-* <s>Spinach</s> — These have been removed from our codebase in May 2018. (`/features/`)
+- [old testing guide](../../testing_guide/frontend_testing.html)
+- [notes on testing Vue components](../../fe_guide/vue.html#testing-vue-components)
 
-## RSpec: Ruby unit tests `/spec/**/*.rb`
+## Frontend unit tests
 
-These tests are meant to unit test the ruby models, controllers and helpers.
+Unit tests are on the lowest abstraction level and typically test functionality that is not directly perceivable by a user.
 
-### When do we write/update these tests?
+### When to use unit tests
 
-Whenever we create or modify any Ruby models, controllers or helpers we add/update corresponding tests.
+<details>
+  <summary>exported functions and classes</summary>
+  Anything that is exported can be reused at various places in a way you have no control over.
+  Therefore it is necessary to document the expected behavior of the public interface with tests.
+</details>
 
----
+<details>
+  <summary>Vuex actions</summary>
+  Any Vuex action needs to work in a consistent way independent of the component it is triggered from.
+</details>
 
-## RSpec: Full feature tests `/spec/features/**/*.rb`
+<details>
+  <summary>Vuex mutations</summary>
+  For complex Vuex mutations it helps to identify the source of a problem by separating the tests from other parts of the Vuex store.
+</details>
 
-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 *not* to use unit tests
 
-### When do we write/update these tests?
+<details>
+  <summary>non-exported functions or classes</summary>
+  Anything that is not exported from a module can be considered private or an implementation detail and doesn't need to be tested.
+</details>
 
-When we add a new feature, we write at least two tests covering the success and the failure scenarios.
+<details>
+  <summary>constants</summary>
+  Testing the value of a constant would mean to copy it.
+  This results in extra effort without additional confidence that the value is correct.
+</details>
+
+<details>
+  <summary>Vue components</summary>
+  Computed properties, methods, and lifecycle hooks can be considered an implementation detail of components and don't need to be tested.
+  They are implicitly covered by component tests.
+  The <a href="https://vue-test-utils.vuejs.org/guides/#getting-started">official Vue guidelines</a> suggest the same.
+</details>
+
+### What to mock in unit tests
+
+<details>
+  <summary>state of the class under test</summary>
+  Modifying the state of the class under test directly rather than using methods of the class avoids side-effects in test setup.
+</details>
+
+<details>
+  <summary>other exported classes</summary>
+  Every class needs to be tested in isolation to prevent test scenarios from growing exponentially.
+</details>
+
+<details>
+  <summary>single DOM elements if passed as parameters</summary>
+  For tests that only operate on single DOM elements rather than a whole page, creating these elements is cheaper than loading a whole HTML fixture.
+</details>
+
+<details>
+  <summary>all server requests</summary>
+  When running frontend unit tests, the backend may not be reachable.
+  Therefore all outgoing requests need to be mocked.
+</details>
+
+<details>
+  <summary>asynchronous background operations</summary>
+  Background operations cannot be stopped or waited on, so they will continue running in the following tests and cause side effects.
+</details>
+
+### What *not* to mock in unit tests
+
+<details>
+  <summary>non-exported functions or classes</summary>
+  Everything that is not exported can be considered private to the module and will be implicitly tested via the exported classes / functions.
+</details>
+
+<details>
+  <summary>methods of the class under test</summary>
+  By mocking methods of the class under test, the mocks will be tested and not the real methods.
+</details>
+
+<details>
+  <summary>utility functions (pure functions, or those that only modify parameters)</summary>
+  If a function has no side effects because it has no state, it is safe to not mock it in tests.
+</details>
+
+<details>
+  <summary>full HTML pages</summary>
+  Loading the HTML of a full page slows down tests, so it should be avoided in unit tests.
+</details>
+
+## Frontend component tests
+
+Component tests cover the state of a single component that is perceivable by a user depending on external signals such as user input, events fired from other components, or application state.
+
+### When to use component tests
+
+- Vue components
+
+### When *not* to use component tests
+
+<details>
+  <summary>Vue applications</summary>
+  Vue applications may contain many components.
+  Testing them on a component level requires too much effort.
+  Therefore they are tested on frontend integration level.
+</details>
+
+<details>
+  <summary>HAML templates</summary>
+  HAML templates contain only Markup and no frontend-side logic.
+  Therefore they are not complete components.
+</details>
+
+### What to mock in component tests
+
+<details>
+  <summary>DOM</summary>
+  Operating on the real DOM is significantly slower than on the virtual DOM.
+</details>
+
+<details>
+  <summary>properties and state of the component under test</summary>
+  Similarly to testing classes, modifying the properties directly (rather than relying on methods of the component) avoids side-effects.
+</details>
+
+<details>
+  <summary>Vuex store</summary>
+  To avoid side effects and keep component tests simple, Vuex stores are replaced with mocks.
+</details>
+
+<details>
+  <summary>all server requests</summary>
+  Similar to unit tests, when running component tests, the backend may not be reachable.
+  Therefore all outgoing requests need to be mocked.
+</details>
+
+<details>
+  <summary>asynchronous background operations</summary>
+  Similar to unit tests, background operations cannot be stopped or waited on, so they will continue running in the following tests and cause side effects.
+</details>
+
+<details>
+  <summary>child components</summary>
+  Every component is tested individually, so child components are mocked.
+  See also <a href="https://vue-test-utils.vuejs.org/api/#shallowmount">shallowMount()</a>
+</details>
+
+### What *not* to mock in component tests
+
+<details>
+  <summary>methods or computed properties of the component under test</summary>
+  By mocking part of the component under test, the mocks will be tested and not the real component.
+</details>
+
+<details>
+  <summary>functions and classes independent from Vue</summary>
+  All plain JavaScript code is already covered by unit tests and needs not to be mocked in component tests.
+</details>
+
+## Frontend integration tests
+
+Integration tests cover the interaction between all components on a single page.
+Their abstraction level is comparable to how a user would interact with the UI.
+
+### When to use integration tests
+
+<details>
+  <summary>page bundles (<code>index.js</code> files in <code>app/assets/javascripts/pages/</code>)</summary>
+  Testing the page bundles ensures the corresponding frontend components integrate well.
+</details>
+
+<details>
+  <summary>Vue applications outside of page bundles</summary>
+  Testing Vue applications as a whole ensures the corresponding frontend components integrate well.
+</details>
+
+### What to mock in integration tests
+
+<details>
+  <summary>HAML views (use fixtures instead)</summary>
+  Rendering HAML views requires a Rails environment including a running database which we cannot rely on in frontend tests.
+</details>
+
+<details>
+  <summary>all server requests</summary>
+  Similar to unit and component tests, when running component tests, the backend may not be reachable.
+  Therefore all outgoing requests need to be mocked.
+</details>
+
+<details>
+  <summary>asynchronous background operations that are not perceivable on the page</summary>
+  Background operations that affect the page need to be tested on this level.
+  All other background operations cannot be stopped or waited on, so they will continue running in the following tests and cause side effects.
+</details>
+
+### What *not* to mock in integration tests
+
+<details>
+  <summary>DOM</summary>
+  Testing on the real DOM ensures our components work in the environment they are meant for.
+  Part of this will be delegated to <a href="https://gitlab.com/gitlab-org/quality/team-tasks/issues/45">cross-browser testing</a>.
+</details>
+
+<details>
+  <summary>properties or state of components</summary>
+  On this level, all tests can only perform actions a user would do.
+  For example to change the state of a component, a click event would be fired.
+</details>
+
+<details>
+  <summary>Vuex stores</summary>
+  When testing the frontend code of a page as a whole, the interaction between Vue components and Vuex stores is covered as well.
+</details>
+
+## Feature tests
+
+In contrast to [frontend integration tests](#frontend-integration-tests), feature tests make requests against the real backend instead of using fixtures.
+This also implies that database queries are executed which makes this category significantly slower.
+
+### When to use feature tests
+
+- use cases that require a backend and cannot be tested using fixtures
+- behavior that is not part of a page bundle but defined globally
 
 ### Relevant notes
 
@@ -48,33 +265,9 @@ 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.
+## Test helpers
 
-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`
+### Vuex Helper: `testAction`
 
 We have a helper available to make testing actions easier, as per [official documentation](https://vuex.vuejs.org/en/testing.html):
 
@@ -97,7 +290,7 @@ testAction(
 
 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`
+### 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`.
 
@@ -133,6 +326,7 @@ afterEach(() => {
   vm.$destroy();
 });
 ```
+
 ## Testing with older browsers
 
 Some regressions only affect a specific browser version. We can install and test in particular browsers with either Firefox or Browserstack using the following steps:
@@ -140,20 +334,21 @@ Some regressions only affect a specific browser version. We can install and test
 
 ### Browserstack
 
-[Browserstack](https://www.browserstack.com/) allows you to test more than 1200 mobile devices and browsers. 
+[Browserstack](https://www.browserstack.com/) allows you to test more than 1200 mobile devices and browsers.
 You can use it directly through the [live app](https://www.browserstack.com/live) or you can install the [chrome extension](https://chrome.google.com/webstore/detail/browserstack/nkihdmlheodkdfojglpcjjmioefjahjb) for easy access.
 You can find the credentials on 1Password, under `frontendteam@gitlab.com`.
 
 ### Firefox
 
 #### macOS
+
 You can download any older version of Firefox from the releases FTP server, https://ftp.mozilla.org/pub/firefox/releases/
 
 1. From the website, select a version, in this case `50.0.1`.
-2. Go to the mac folder.
-3. Select your preferred language, you will find the dmg package inside, download it.
-4. Drag and drop the application to any other folder but the `Applications` folder.
-5. Rename the application to something like `Firefox_Old`.
-6. Move the application to the `Applications` folder.
-7. Open up a terminal and run `/Applications/Firefox_Old.app/Contents/MacOS/firefox-bin -profilemanager` to create a new profile specific to that Firefox version.
-8. Once the profile has been created, quit the app, and run it again like normal. You now have a working older Firefox version.
+1. Go to the mac folder.
+1. Select your preferred language, you will find the dmg package inside, download it.
+1. Drag and drop the application to any other folder but the `Applications` folder.
+1. Rename the application to something like `Firefox_Old`.
+1. Move the application to the `Applications` folder.
+1. Open up a terminal and run `/Applications/Firefox_Old.app/Contents/MacOS/firefox-bin -profilemanager` to create a new profile specific to that Firefox version.
+1. Once the profile has been created, quit the app, and run it again like normal. You now have a working older Firefox version.
diff --git a/doc/development/new_fe_guide/index.md b/doc/development/new_fe_guide/index.md
index 78931defa24..bfcca9cec7b 100644
--- a/doc/development/new_fe_guide/index.md
+++ b/doc/development/new_fe_guide/index.md
@@ -19,6 +19,10 @@ Guidance on topics related to development.
 
 Learn about all the dependencies that make up our frontend, including some of our own custom built libraries.
 
+## [Modules](modules/index.md)
+
+Learn about all the internal JavaScript modules that make up our frontend.
+
 ## [Style guides](style/index.md)
 
 Style guides to keep our code consistent.
diff --git a/doc/development/new_fe_guide/modules/dirty_submit.md b/doc/development/new_fe_guide/modules/dirty_submit.md
new file mode 100644
index 00000000000..6c03958b463
--- /dev/null
+++ b/doc/development/new_fe_guide/modules/dirty_submit.md
@@ -0,0 +1,23 @@
+# Dirty Submit
+
+> [Introduced][ce-21115] in GitLab 11.3.  
+> [dirty_submit][dirty-submit]
+
+## Summary
+
+Prevent submitting forms with no changes.
+
+Currently handles `input`, `textarea` and `select` elements.
+
+## Usage
+
+```js
+import dirtySubmitFactory from './dirty_submit/dirty_submit_form';
+
+new DirtySubmitForm(document.querySelector('form'));
+// or
+new DirtySubmitForm(document.querySelectorAll('form'));
+```
+
+[ce-21115]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/21115
+[dirty-submit]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/assets/javascripts/dirty_submit/
\ No newline at end of file
diff --git a/doc/development/new_fe_guide/modules/index.md b/doc/development/new_fe_guide/modules/index.md
new file mode 100644
index 00000000000..0a7f2dbd819
--- /dev/null
+++ b/doc/development/new_fe_guide/modules/index.md
@@ -0,0 +1,5 @@
+# Modules
+
+* [DirtySubmit](dirty_submit.md)
+
+  Disable form submits until there are unsaved changes.
\ No newline at end of file
diff --git a/doc/development/new_fe_guide/style/prettier.md b/doc/development/new_fe_guide/style/prettier.md
index 6395af6f815..baaea67d38b 100644
--- a/doc/development/new_fe_guide/style/prettier.md
+++ b/doc/development/new_fe_guide/style/prettier.md
@@ -47,13 +47,13 @@ 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/
+node ./scripts/frontend/prettier.js check-all ./vendor/
 ```
 
 This will go over all files in a specific folder check it.
 
 ```
-node ./scripts/frontend/prettier.js save ./vendor/
+node ./scripts/frontend/prettier.js save-all ./vendor/
 ```
 
 This will go over all files in a specific folder and save it.
diff --git a/doc/development/ordering_table_columns.md b/doc/development/ordering_table_columns.md
index 5d00e1f7a0c..e9c6481635b 100644
--- a/doc/development/ordering_table_columns.md
+++ b/doc/development/ordering_table_columns.md
@@ -1,32 +1,49 @@
-# Ordering Table Columns
+# Ordering Table Columns in PostgreSQL
 
 Similar to C structures the space of a table is influenced by the order of
 columns. This is because the size of columns is aligned depending on the type of
-the column. Take the following column order for example:
+the following column. Let's consider an example:
 
-* id (integer, 4 bytes)
-* name (text, variable)
-* user_id (integer, 4 bytes)
+- `id` (integer, 4 bytes)
+- `name` (text, variable)
+- `user_id` (integer, 4 bytes)
 
-Integers are aligned to the word size. This means that on a 64 bit platform the
-actual size of each column would be: 8 bytes, variable, 8 bytes. This means that
-each row will require at least 16 bytes for the two integers, and a variable
-amount for the text field. If a table has a few rows this is not an issue, but
-once you start storing millions of rows you can save space by using a different
-order. For the above example a more ideal column order would be the following:
+The first column is a 4-byte integer. The next is text of variable length. The
+`text` data type requires 1-word alignment, and on 64-bit platform, 1 word is 8
+bytes. To meet the alignment requirements, four zeros are to be added right
+after the first column, so `id` occupies 4 bytes, then 4 bytes of alignment
+padding, and only next `name` is being stored. Therefore, in this case, 8 bytes
+will be spent for storing a 4-byte integer.
 
-* id (integer, 4 bytes)
-* user_id (integer, 4 bytes)
-* name (text, variable)
+The space between rows is also subject to alignment padding. The `user_id`
+column takes only 4 bytes, and on 64-bit platform, 4 zeroes will be added for
+alignment padding, to allow storing the next row beginning with the "clear" word.
 
-In this setup the `id` and `user_id` columns can be packed together, which means
-we only need 8 bytes to store _both_ of them. This in turn each row will require
-8 bytes less of space.
+As a result, the actual size of each column would be (ommiting variable length
+data and 24-byte tuple header): 8 bytes, variable, 8 bytes. This means that
+each row will require at least 16 bytes for the two 4-byte integers. If a table
+has a few rows this is not an issue. However, once you start storing millions of
+rows you can save space by using a different order. For the above example, the
+ideal column order would be the following:
+
+- `id` (integer, 4 bytes)
+- `user_id` (integer, 4 bytes)
+- `name` (text, variable)
+
+or 
+
+- `name` (text, variable)
+- `id` (integer, 4 bytes)
+- `user_id` (integer, 4 bytes)
+
+In these examples, the `id` and `user_id` columns are packed together, which
+means we only need 8 bytes to store _both_ of them. This in turn means each row
+will require 8 bytes less space.
 
 For GitLab we require that columns of new tables are ordered based to use the
 least amount of space. An easy way of doing this is to order them based on the
-type size in descending order with variable sizes (string and text columns for
-example) at the end.
+type size in descending order with variable sizes (`text`, `varchar`, arrays,
+`json`, `jsonb`, and so on) at the end.
 
 ## Type Sizes
 
@@ -36,7 +53,7 @@ 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
 bits platform and 8 bytes for a 64 bits platform.
 
-| Type             | Size                                 | Aligned To |
+| Type             | Size                                 | Alignment needed |
 |:-----------------|:-------------------------------------|:-----------|
 | smallint         | 2 bytes                              | 1 word     |
 | integer          | 4 bytes                              | 1 word     |
@@ -58,7 +75,7 @@ always be at the end of a table.
 
 ## Real Example
 
-Let's use the "events" table as an example, which currently has the following
+Let's use the `events` table as an example, which currently has the following
 layout:
 
 | Column      | Type                        | Size     |
@@ -89,8 +106,8 @@ divided into fixed size chunks as follows:
 | 8 bytes    | updated_at        |
 | 8 bytes    | action, author_id |
 
-This means that excluding the variable sized data we need at least 48 bytes per
-row.
+This means that excluding the variable sized data and tuple header, we need at
+least 8 * 6 = 48 bytes per row.
 
 We can optimise this by using the following column order instead:
 
@@ -120,8 +137,8 @@ This would produce the following chunks:
 | variable   | title              |
 | variable   | data               |
 
-Here we only need 40 bytes per row excluding the variable sized data. 8 bytes
-being saved may not sound like much, but for tables as large as the "events"
-table it does begin to matter. For example, when storing 80 000 000 rows this
-translates to a space saving of at least 610 MB: all by just changing the order
-of a few columns.
+Here we only need 40 bytes per row excluding the variable sized data and 24-byte
+tuple header. 8 bytes being saved may not sound like much, but for tables as 
+large as the `events` table it does begin to matter. For example, when storing
+80 000 000 rows this translates to a space saving of at least 610 MB, all by
+just changing the order of a few columns.
diff --git a/doc/development/performance.md b/doc/development/performance.md
index 05caffb150a..4cc2fdc9a58 100644
--- a/doc/development/performance.md
+++ b/doc/development/performance.md
@@ -9,17 +9,17 @@ The process of solving performance problems is roughly as follows:
 
 1. Make sure there's an issue open somewhere (e.g., on the GitLab CE issue
    tracker), create one if there isn't. See [#15607][#15607] for an example.
-2. Measure the performance of the code in a production environment such as
+1. Measure the performance of the code in a production environment such as
    GitLab.com (see the [Tooling](#tooling) section below). Performance should be
    measured over a period of _at least_ 24 hours.
-3. Add your findings based on the measurement period (screenshots of graphs,
+1. Add your findings based on the measurement period (screenshots of graphs,
    timings, etc) to the issue mentioned in step 1.
-4. Solve the problem.
-5. Create a merge request, assign the "Performance" label and assign it to
+1. Solve the problem.
+1. Create a merge request, assign the "Performance" label and assign it to
    [@yorickpeterse][yorickpeterse] for reviewing.
-6. Once a change has been deployed make sure to _again_ measure for at least 24
+1. Once a change has been deployed make sure to _again_ measure for at least 24
    hours to see if your changes have any impact on the production environment.
-7. Repeat until you're done.
+1. Repeat until you're done.
 
 When providing timings make sure to provide:
 
@@ -34,13 +34,14 @@ graphs/dashboards.
 
 ## Tooling
 
-GitLab provides built-in tools to aid the process of improving performance:
+GitLab provides built-in tools to help improve performance and availability:
 
 * [Profiling](profiling.md)
   * [Sherlock](profiling.md#sherlock)
 * [GitLab Performance Monitoring](../administration/monitoring/performance/index.md)
 * [Request Profiling](../administration/monitoring/performance/request_profiling.md)
 * [QueryRecoder](query_recorder.md) for preventing `N+1` regressions
+* [Chaos endpoints](chaos_endpoints.md) for testing failure scenarios. Intended mainly for testing availability.
 
 GitLab employees can use GitLab.com's performance monitoring systems located at
 <https://dashboards.gitlab.net>, this requires you to log in using your
@@ -93,14 +94,14 @@ result of this should be used instead of the `Benchmark` module.
 
 In short:
 
-1. Don't trust benchmarks you find on the internet.
-2. Never make claims based on just benchmarks, always measure in production to
+- Don't trust benchmarks you find on the internet.
+- Never make claims based on just benchmarks, always measure in production to
    confirm your findings.
-3. X being N times faster than Y is meaningless if you don't know what impact it
+- X being N times faster than Y is meaningless if you don't know what impact it
    will actually have on your production environment.
-4. A production environment is the _only_ benchmark that always tells the truth
+- A production environment is the _only_ benchmark that always tells the truth
    (unless your performance monitoring systems are not set up correctly).
-5. If you must write a benchmark use the benchmark-ips Gem instead of Ruby's
+- If you must write a benchmark use the benchmark-ips Gem instead of Ruby's
    `Benchmark` module.
 
 ## Profiling
@@ -364,8 +365,7 @@ Depending on the size of the String and how frequently it would be allocated
 there's no guarantee it will.
 
 Strings will be frozen by default in Ruby 3.0. To prepare our code base for
-this eventuality, it's a good practice to add the following header to all
-Ruby files:
+this eventuality, we will be adding the following header to all Ruby files:
 
 ```ruby
 # frozen_string_literal: true
@@ -379,6 +379,9 @@ test = +"hello"
 test += " world"
 ```
 
+When adding new Ruby files, please check that you can add the above header,
+as omitting it may lead to style check failures.
+
 ## Anti-Patterns
 
 This is a collection of [anti-patterns][anti-pattern] that should be avoided
diff --git a/doc/development/post_deployment_migrations.md b/doc/development/post_deployment_migrations.md
index cfc91539bee..5986efa9974 100644
--- a/doc/development/post_deployment_migrations.md
+++ b/doc/development/post_deployment_migrations.md
@@ -57,13 +57,13 @@ depends on this column being present while it's running. Normally you'd follow
 these steps in such a case:
 
 1. Stop the GitLab instance
-2. Run the migration removing the column
-3. Start the GitLab instance again
+1. Run the migration removing the column
+1. Start the GitLab instance again
 
 Using post deployment migrations we can instead follow these steps:
 
 1. Deploy a new version of GitLab while ignoring post deployment migrations
-2. Re-run `rake db:migrate` but without the environment variable set
+1. Re-run `rake db:migrate` but without the environment variable set
 
 Here we don't need any downtime as the migration takes place _after_ a new
 version (which doesn't depend on the column anymore) has been deployed.
diff --git a/doc/development/query_count_limits.md b/doc/development/query_count_limits.md
index 310e3faf61b..b3ecaf30d8a 100644
--- a/doc/development/query_count_limits.md
+++ b/doc/development/query_count_limits.md
@@ -8,8 +8,8 @@ in test environments we'll raise an error when this threshold is exceeded.
 When a test fails because it executes more than 100 SQL queries there are two
 solutions to this problem:
 
-1. Reduce the number of SQL queries that are executed.
-2. Whitelist the controller or API endpoint.
+- Reduce the number of SQL queries that are executed.
+- Whitelist the controller or API endpoint.
 
 You should only resort to whitelisting when an existing controller or endpoint
 is to blame as in this case reducing the number of SQL queries can take a lot of
diff --git a/doc/development/rake_tasks.md b/doc/development/rake_tasks.md
index fc51b74da1d..2ad748d4802 100644
--- a/doc/development/rake_tasks.md
+++ b/doc/development/rake_tasks.md
@@ -1,6 +1,6 @@
 # Rake tasks for developers
 
-## Setup db with developer seeds
+## Set up db with developer seeds
 
 Note that if your db user does not have advanced privileges you must create the db manually before running this command.
 
diff --git a/doc/development/rolling_out_changes_using_feature_flags.md b/doc/development/rolling_out_changes_using_feature_flags.md
index 905aa26a40b..b65fbc9d958 100644
--- a/doc/development/rolling_out_changes_using_feature_flags.md
+++ b/doc/development/rolling_out_changes_using_feature_flags.md
@@ -151,3 +151,40 @@ most cases this will translate to a feature (with a feature flag) being shipped
 in RC1, followed by the feature flag being removed in RC2. This in turn means
 the feature will be stable by the time we publish a stable package around the
 22nd of the month.
+
+## Implicit feature flags
+
+The [`Project#feature_available?`][project-fa],
+[`Namespace#feature_available?`][namespace-fa] (EE), and
+[`License.feature_available?`][license-fa] (EE) methods all implicitly check for
+a feature flag by the same name as the provided argument.
+
+For example if a feature is license-gated, there's no need to add an additional
+explicit feature flag check since the flag will be checked as part of the
+`License.feature_available?` call. Similarly, there's no need to "clean up" a
+feature flag once the feature has reached general availability.
+
+You'd still want to use an explicit `Feature.enabled?` check if your new feature
+isn't gated by a License or Plan.
+
+[project-fa]: https://gitlab.com/gitlab-org/gitlab-ee/blob/4cc1c62918aa4c31750cb21dfb1a6c3492d71080/app/models/project_feature.rb#L63-68
+[namespace-fa]: https://gitlab.com/gitlab-org/gitlab-ee/blob/4cc1c62918aa4c31750cb21dfb1a6c3492d71080/ee/app/models/ee/namespace.rb#L71-85
+[license-fa]: https://gitlab.com/gitlab-org/gitlab-ee/blob/4cc1c62918aa4c31750cb21dfb1a6c3492d71080/ee/app/models/license.rb#L293-300
+
+### Undefined feature flags default to "on"
+
+An important side-effect of the [implicit feature
+flags][#implicit-feature-flags] mentioned above is that unless the feature is
+explicitly disabled or limited to a percentage of users, the feature flag check
+will default to `true`.
+
+As an example, if you were to ship the backend half of a feature behind a flag,
+you'd want to explicitly disable that flag until the frontend half is also ready
+to be shipped. You can do this via ChatOps:
+
+```
+/chatops run feature set some_feature 0
+```
+
+Note that you can do this at any time, even before the merge request using the
+flag has been merged!
diff --git a/doc/development/sidekiq_style_guide.md b/doc/development/sidekiq_style_guide.md
index 76ff51446ba..8e268224c98 100644
--- a/doc/development/sidekiq_style_guide.md
+++ b/doc/development/sidekiq_style_guide.md
@@ -17,8 +17,8 @@ would be `process_something`. If you're not sure what queue a worker uses,
 you can find it using `SomeWorker.queue`. There is almost never a reason to
 manually override the queue name using `sidekiq_options queue: :some_queue`.
 
-You must always add any new queues to `app/workers/all_queues.yml` otherwise
-your worker will not run.
+You must always add any new queues to `app/workers/all_queues.yml` or `ee/app/workers/all_queues.yml`
+otherwise your worker will not run.
 
 ## Queue Namespaces
 
diff --git a/doc/development/swapping_tables.md b/doc/development/swapping_tables.md
index 6b990ece72c..29cd6a43aff 100644
--- a/doc/development/swapping_tables.md
+++ b/doc/development/swapping_tables.md
@@ -8,8 +8,8 @@ Let's say you want to swap the table "events" with "events_for_migration". In
 this case you need to follow 3 steps:
 
 1. Rename "events" to "events_temporary"
-2. Rename "events_for_migration" to "events"
-3. Rename "events_temporary" to "events_for_migration"
+1. Rename "events_for_migration" to "events"
+1. Rename "events_temporary" to "events_for_migration"
 
 Rails allows you to do this using the `rename_table` method:
 
diff --git a/doc/development/switching_to_rails5.md b/doc/development/switching_to_rails5.md
new file mode 100644
index 00000000000..c9a4ce1a1d1
--- /dev/null
+++ b/doc/development/switching_to_rails5.md
@@ -0,0 +1,27 @@
+# Switching to Rails 5
+
+GitLab switched recently to Rails 5. This is a big change (especially for backend development) and it introduces couple of temporary inconveniences.
+
+## After the switch, I found a broken feature. What do I do?
+
+Many fixes and tweaks were done to make our codebase compatible with Rails 5, but it's possible that not all issues were found. If you find an bug, please create an issue and assign it the ~rails5 label.
+
+## It takes much longer to run CI pipelines that build GitLab. Why?
+
+We are temporarily running CI pipelines with Rails 4 and 5 so that we ensure we remain compatible with Rails 4 in case we must revert back to Rails 4 from Rails 5 (this can double the duration of CI pipelines).
+
+We might revert back to Rails 4 if we found a major issue we were unable to quickly fix.
+
+Once we are sure we can stay with Rails 5, we will stop running CI pipelines with Rails 4.
+
+## Can I skip running Rails 4 tests?
+
+If you are sure that your merge request doesn't introduce any incompatibility, you can just include `norails4` anywhere in your branch name and Rails 4 tests will be skipped.
+
+## CI is failing on my test with Rails 4. How can I debug it?
+
+You can run specs locally with Rails 4 using the following command:
+
+```sh
+BUNDLE_GEMFILE=Gemfile.rails4 RAILS5=0 bundle exec rspec ...
+```
diff --git a/doc/development/testing_guide/best_practices.md b/doc/development/testing_guide/best_practices.md
index acbfa1850b4..72abda26e3d 100644
--- a/doc/development/testing_guide/best_practices.md
+++ b/doc/development/testing_guide/best_practices.md
@@ -209,6 +209,130 @@ it 'is overdue' do
 end
 ```
 
+### Pristine test environments
+
+The code exercised by a single GitLab test may access and modify many items of
+data. Without careful preparation before a test runs, and cleanup afterward,
+data can be changed by a test in such a way that it affects the behaviour of
+following tests. This should be avoided at all costs! Fortunately, the existing
+test framework handles most cases already.
+
+When the test environment does get polluted, a common outcome is
+[flaky tests](flaky_tests.md). Pollution will often manifest as an order
+dependency: running spec A followed by spec B will reliably fail, but running
+spec B followed by spec A will reliably succeed. In these cases, you can use
+`rspec --bisect` (or a manual pairwise bisect of spec files) to determine which
+spec is at fault. Fixing the problem requires some understanding of how the test
+suite ensures the environment is pristine. Read on to discover more about each
+data store!
+
+#### SQL database
+
+This is managed for us by the `database_cleaner` gem. Each spec is surrounded in
+a transaction, which is rolled back once the test completes. Certain specs will
+instead issue `DELETE FROM` queries against every table after completion; this
+allows the created rows to be viewed from multiple database connections, which
+is important for specs that run in a browser, or migration specs, among others.
+
+One consequence of using these strategies, instead of the well-known
+`TRUNCATE TABLES` approach, is that primary keys and other sequences are **not**
+reset across specs. So if you create a project in spec A, then create a project
+in spec B, the first will have `id=1`, while the second will have `id=2`.
+
+This means that specs should **never** rely on the value of an ID, or any other
+sequence-generated column. To avoid accidental conflicts, specs should also
+avoid manually specifying any values in these kinds of columns. Instead, leave
+them unspecified, and look up the value after the row is created.
+
+#### Redis
+
+GitLab stores two main categories of data in Redis: cached items, and sidekiq
+jobs.
+
+In most specs, the Rails cache is actually an in-memory store. This is replaced
+between specs, so calls to `Rails.cache.read` and `Rails.cache.write` are safe.
+However, if a spec makes direct Redis calls, it should mark itself with the
+`:clean_gitlab_redis_cache`, `:clean_gitlab_redis_shared_state` or
+`:clean_gitlab_redis_queues` traits as appropriate.
+
+Sidekiq jobs are typically not run in specs, but this behaviour can be altered
+in each spec through the use of `Sidekiq::Testing.inline!` blocks. Any spec that
+causes Sidekiq jobs to be pushed to Redis should use the `:sidekiq` trait, to
+ensure that they are removed once the spec completes.
+
+#### Filesystem
+
+Filesystem data can be roughly split into "repositories", and "everything else".
+Repositories are stored in `tmp/tests/repositories`. This directory is emptied
+before a test run starts, and after the test run ends. It is not emptied between
+specs, so created repositories accumulate within this directory over the
+lifetime of the process. Deleting them is expensive, but this could lead to
+pollution unless carefully managed.
+
+To avoid this, [hashed storage](../../administration/repository_storage_types.md)
+is enabled in the test suite. This means that repositories are given a unique
+path that depends on their project's ID. Since the project IDs are not reset
+between specs, this guarantees that each spec gets its own repository on disk,
+and prevents changes from being visible between specs.
+
+If a spec manually specifies a project ID, or inspects the state of the
+`tmp/tests/repositories/` directory directly, then it should clean up the
+directory both before and after it runs. In general, these patterns should be
+completely avoided.
+
+Other classes of file linked to database objects, such as uploads, are generally
+managed in the same way. With hashed storage enabled in the specs, they are
+written to disk in locations determined by ID, so conflicts should not occur.
+
+Some specs disable hashed storage by passing the `:legacy_storage` trait to the
+`projects` factory. Specs that do this must **never** override the `path` of the
+project, or any of its groups. The default path includes the project ID, so will
+not conflict; but if two specs create a `:legacy_storage` project with the same
+path, they will use the same repository on disk and lead to test environment
+pollution.
+
+Other files must be managed manually by the spec. If you run code that creates a
+`tmp/test-file.csv` file, for instance, the spec must ensure that the file is 
+removed as part of cleanup.
+
+#### Persistent in-memory application state
+
+All the specs in a given `rspec` run share the same Ruby process, which means
+they can affect each other by modifying Ruby objects that are accessible between
+specs. In practice, this means global variables, and constants (which includes
+Ruby classes, modules, etc).
+
+Global variables should generally not be modified. If absolutely necessary, a
+block like this can be used to ensure the change is rolled back afterwards:
+
+```ruby
+around(:each) do |example|
+  old_value = $0
+
+  begin
+    $0 = "new-value"
+    example.run
+  ensure
+    $0 = old_value
+  end
+end
+```
+
+If a spec needs to modify a constant, it should use the `stub_const` helper to
+ensure the change is rolled back.
+
+If you need to modify the contents of the `ENV` constant, you can use the
+`stub_env` helper method instead.
+
+While most Ruby **instances** are not shared between specs, **classes**
+and **modules** generally are. Class and module instance variables, accessors,
+class variables, and other stateful idioms, should be treated in the same way as
+global variables - don't modify them unless you have to! In particular, prefer
+using expectations, or dependency injection along with stubs, to avoid the need
+for modifications. If you have no other choice, an `around` block similar to the
+example for global variables, above, can be used, but this should be avoided if
+at all possible.
+
 ### Table-based / Parameterized tests
 
 This style of testing is used to exercise one piece of code with a comprehensive
@@ -270,7 +394,7 @@ This is especially useful whenever it's showing 500 internal server error.
 
 ### Shared contexts
 
-All shared contexts should be be placed under `spec/support/shared_contexts/`.
+All shared contexts should be placed under `spec/support/shared_contexts/`.
 Shared contexts can be placed in subfolder if they apply to a certain type of
 specs only (e.g. features, requests etc.) but shouldn't be if they apply to
 multiple type of specs.
@@ -280,7 +404,7 @@ Each file should include only one context and have a descriptive name, e.g.
 
 ### Shared examples
 
-All shared examples should be be placed under `spec/support/shared_examples/`.
+All shared examples should be placed under `spec/support/shared_examples/`.
 Shared examples can be placed in subfolder if they apply to a certain type of
 specs only (e.g. features, requests etc.) but shouldn't be if they apply to
 multiple type of specs.
@@ -292,7 +416,7 @@ Each file should include only one context and have a descriptive name, e.g.
 
 Helpers are usually modules that provide some methods to hide the complexity of
 specific RSpec examples. You can define helpers in RSpec files if they're not
-intended to be shared with other specs. Otherwise, they should be be placed
+intended to be shared with other specs. Otherwise, they should be placed
 under `spec/support/helpers/`. Helpers can be placed in subfolder if they apply
 to a certain type of specs only (e.g. features, requests etc.) but shouldn't be
 if they apply to multiple type of specs.
@@ -346,7 +470,38 @@ GitLab uses [factory_bot] as a test fixture replacement.
 
 ### Fixtures
 
-All fixtures should be be placed under `spec/fixtures/`.
+All fixtures should be placed under `spec/fixtures/`.
+
+### Repositories
+
+Testing some functionality, e.g., merging a merge request, requires a git
+repository with a certain state to be present in the test environment. GitLab
+maintains the [gitlab-test](https://gitlab.com/gitlab-org/gitlab-test)
+repository for certain common cases - you can ensure a copy of the repository is
+used with the `:repository` trait for project factories:
+
+```ruby
+let(:project) { create(:project, :repository) }
+```
+
+Where you can, consider using the `:custom_repo` trait instead of `:repository`.
+This allows you to specify exactly what files will appear in the `master` branch
+of the project's repository. For example:
+
+```ruby
+let(:project) do
+  create(
+    :project, :custom_repo,
+    files: {
+      'README.md'       => 'Content here',
+      'foo/bar/baz.txt' => 'More content here'
+    }
+  )
+end
+```
+
+This will create a repository containing two files, with default permissions and
+the specified content.
 
 ### Config
 
diff --git a/doc/development/testing_guide/end_to_end_tests.md b/doc/development/testing_guide/end_to_end_tests.md
index 21ec926414d..e9f236c6b3a 100644
--- a/doc/development/testing_guide/end_to_end_tests.md
+++ b/doc/development/testing_guide/end_to_end_tests.md
@@ -1,32 +1,37 @@
-# End-to-End Testing
+# End-to-end Testing
 
-## What is End-to-End testing?
+## What is end-to-end testing?
 
-End-to-End testing is a strategy used to check whether your application works
-as expected across entire software stack and architecture, including
-integration of all microservices and components that are supposed to work
+End-to-end testing is a strategy used to check whether your application works
+as expected across the entire software stack and architecture, including
+integration of all micro-services and components that are supposed to work
 together.
 
 ## How do we test GitLab?
 
 We use [Omnibus GitLab][omnibus-gitlab] to build GitLab packages and then we
-test these packages using [GitLab QA][gitlab-qa] project, which is entirely
-black-box, click-driven testing framework.
+test these packages using the [GitLab QA orchestrator][gitlab-qa] tool, which is
+a black-box testing framework for the API and the UI.
 
 ### Testing nightly builds
 
 We run scheduled pipeline each night to test nightly builds created by Omnibus.
-You can find these nightly pipelines at [GitLab QA pipelines page][gitlab-qa-pipelines].
+You can find these nightly pipelines at [gitlab-org/quality/nightly/pipelines][quality-nightly-pipelines].
+
+### Testing staging
+
+We run scheduled pipeline each night to test staging.
+You can find these nightly pipelines at [gitlab-org/quality/staging/pipelines][quality-staging-pipelines].
 
 ### Testing code in merge requests
 
 It is possible to run end-to-end tests (eventually being run within a
 [GitLab QA pipeline][gitlab-qa-pipelines]) for a merge request by triggering
-the `package-and-qa` manual action, that should be present in a merge request
-widget.
+the `package-and-qa` manual action in the `test` stage, that should be present
+in a merge request widget (unless the merge request is from a fork).
 
 Manual action that starts end-to-end tests is also available in merge requests
-in Omnibus GitLab project.
+in [Omnibus GitLab][omnibus-gitlab].
 
 Below you can read more about how to use it and how does it work.
 
@@ -35,46 +40,56 @@ Below you can read more about how to use it and how does it work.
 Currently, we are using _multi-project pipeline_-like approach to run QA
 pipelines.
 
-1. Developer triggers a manual action, that can be found in CE and EE merge
+1. Developer triggers a manual action, that can be found in CE / EE merge
 requests. This starts a chain of pipelines in multiple projects.
 
-1. The script being executed triggers a pipeline in GitLab Omnibus and waits
-for the resulting status. We call this a _status attribution_.
+1. The script being executed triggers a pipeline in [Omnibus GitLab][omnibus-gitlab]
+and waits for the resulting status. We call this a _status attribution_.
 
-1. GitLab packages are being built in Omnibus pipeline. Packages are going to be
-pushed to Container Registry.
+1. GitLab packages are being built in the [Omnibus GitLab][omnibus-gitlab]
+pipeline. Packages are then pushed to its Container Registry.
 
 1. When packages are ready, and available in the registry, a final step in the
-pipeline, that is now running in Omnibus, triggers a new pipeline in the GitLab
-QA project. It also waits for a resulting status.
+[Omnibus GitLab][omnibus-gitlab] pipeline, triggers a new
+[GitLab QA pipeline][gitlab-qa-pipelines]. It also waits for a resulting status.
 
 1. GitLab QA pulls images from the registry, spins-up containers and runs tests
 against a test environment that has been just orchestrated by the `gitlab-qa`
 tool.
 
-1. The result of the GitLab QA pipeline is being propagated upstream, through
-Omnibus, back to CE / EE merge request.
+1. The result of the [GitLab QA pipeline][gitlab-qa-pipelines] is being
+propagated upstream, through Omnibus, back to the CE / EE merge request.
 
 #### How do I write tests?
 
 In order to write new tests, you first need to learn more about GitLab QA
-architecture. See the [documentation about it][gitlab-qa-architecture] in
-GitLab QA project.
+architecture. See the [documentation about it][gitlab-qa-architecture].
 
-Once you decided where to put test environment orchestration scenarios and
-instance specs, take a look at the [relevant documentation][instance-qa-readme]
-and examples in [the `qa/` directory][instance-qa-examples].
+Once you decided where to put [test environment orchestration scenarios] and
+[instance-level scenarios], take a look at the [GitLab QA README][instance-qa-readme],
+the [GitLab QA orchestrator README][gitlab-qa-readme], and [the already existing
+instance-level scenarios][instance-level scenarios].
 
 ## Where can I ask for help?
 
 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.
+[the `gitlab-ce` issue tracker][gitlab-ce-issues],
+[the `gitlab-ee` issue tracker][gitlab-ce-issues], or
+[the `gitlab-qa` issue tracker][gitlab-qa-issues].
 
 [omnibus-gitlab]: https://gitlab.com/gitlab-org/omnibus-gitlab
 [gitlab-qa]: https://gitlab.com/gitlab-org/gitlab-qa
+[gitlab-qa-readme]: https://gitlab.com/gitlab-org/gitlab-qa/tree/master/README.md
 [gitlab-qa-pipelines]: https://gitlab.com/gitlab-org/gitlab-qa/pipelines
+[quality-nightly-pipelines]: https://gitlab.com/gitlab-org/quality/nightly/pipelines
+[quality-staging-pipelines]: https://gitlab.com/gitlab-org/quality/staging/pipelines
 [gitlab-qa-architecture]: https://gitlab.com/gitlab-org/gitlab-qa/blob/master/docs/architecture.md
-[gitlab-qa-issues]: https://gitlab.com/gitlab-org/gitlab-qa/issues
+[gitlab-qa-issues]: https://gitlab.com/gitlab-org/gitlab-qa/issues?label_name%5B%5D=new+scenario
+[gitlab-ce-issues]: https://gitlab.com/gitlab-org/gitlab-ce/issues?label_name[]=QA&label_name[]=test
+[gitlab-ee-issues]: https://gitlab.com/gitlab-org/gitlab-ee/issues?label_name[]=QA&label_name[]=test
+[test environment orchestration scenarios]: https://gitlab.com/gitlab-org/gitlab-qa/tree/master/lib/gitlab/qa/scenario
+[instance-level scenarios]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/qa/qa/specs/features
+[Page objects documentation]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/qa/qa/page/README.md
 [instance-qa-readme]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/qa/README.md
 [instance-qa-examples]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/qa/qa
diff --git a/doc/development/testing_guide/review_apps.md b/doc/development/testing_guide/review_apps.md
index 38ea2f1dde1..a6ed9e85a41 100644
--- a/doc/development/testing_guide/review_apps.md
+++ b/doc/development/testing_guide/review_apps.md
@@ -1,81 +1,104 @@
-# Review apps
+# Review Apps
 
-We currently have review apps available as a manual job in EE pipelines. Here is
-[the first implementation](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6259).
-
-That said, [the Quality team is working](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6665)
-on making Review Apps automatically deployed by each pipeline, both in CE and EE.
+Review Apps are automatically deployed by each pipeline, both in
+[CE](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22010) and
+[EE](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6665).
 
 ## How does it work?
 
-1. On every EE [pipeline][gitlab-pipeline] during the `test` stage, you can
-  start the [`review` job][review-job]
-1. The `review` job [triggers a pipeline][cng-pipeline] in the
-  [`CNG-mirror`][cng-mirror] [^1] project
-1. The `CNG-mirror` pipeline creates the Docker images of each component (e.g. `gitlab-rails-ee`,
-  `gitlab-shell`, `gitaly` etc.) based on the commit from the
-  [GitLab pipeline][gitlab-pipeline] and store them in its
-  [registry][cng-mirror-registry]
-1. Once all images are built, the review app is deployed using
-  [the official GitLab Helm chart][helm-chart] [^2] to the
-  [`review-apps-ee` Kubernetes cluster on GCP][review-apps-ee]
-  - The actual scripts used to deploy the review app can be found at
-    [`scripts/review_apps/review-apps.sh`][review-apps.sh]
-  - These scripts are basically
-    [our official Auto DevOps scripts][Auto-DevOps.gitlab-ci.yml] where the
-    default CNG images are overriden with the images built and stored in the
-    [`CNG-mirror` project's registry][cng-mirror-registry]
-1. Once the `review` job succeeds, you should be able to use your review app
-  thanks to the direct link to it from the MR widget. The default username is
-  `root` and its password can be found in the 1Password secure note named
-  **gitlab-{ce,ee} review app's root password**.
+1. On every [pipeline][gitlab-pipeline] during the `test` stage, the
+  [`review-deploy`][review-deploy-job] job is automatically started.
+1. The `review-deploy` job:
+    1. Waits for the `gitlab:assets:compile` job to finish since the
+      [`CNG-mirror`][cng-mirror] pipeline triggerred in the following step
+      depends on it.
+    1. [Triggers a pipeline][cng-pipeline] in the [`CNG-mirror`][cng-mirror]
+      project.
+        - We use the `CNG-mirror` project so that the `CNG`, (**C**loud
+          **N**ative **G**itLab), project's registry is not overloaded with a
+          lot of transient Docker images.
+        - The `CNG-mirror` pipeline creates the Docker images of each component
+          (e.g. `gitlab-rails-ee`, `gitlab-shell`, `gitaly` etc.) based on the
+          commit from the [GitLab pipeline][gitlab-pipeline] and store them in
+          its [registry][cng-mirror-registry].
+    1. Once all images are built by [`CNG-mirror`][cng-mirror], the Review App
+      is deployed using [the official GitLab Helm chart][helm-chart] to the
+      [`review-apps-ce`][review-apps-ce] / [`review-apps-ee`][review-apps-ee]
+      Kubernetes cluster on GCP.
+        - The actual scripts used to deploy the Review App can be found at
+          [`scripts/review_apps/review-apps.sh`][review-apps.sh].
+        - These scripts are basically
+          [our official Auto DevOps scripts][Auto-DevOps.gitlab-ci.yml] where the
+          default CNG images are overridden with the images built and stored in the
+          [`CNG-mirror` project's registry][cng-mirror-registry].
+        - Since we're using [the official GitLab Helm chart][helm-chart], this means
+          you get a dedicated environment for your branch that's very close to what
+          it would look in production.
+1. Once the `review-deploy` job succeeds, you should be able to use your Review
+  App thanks to the direct link to it from the MR widget. The default username
+  is `root` and its password can be found in the 1Password secure note named
+  **gitlab-{ce,ee} Review App's root password** (note that there's currently
+  [a bug where the default password seems to be overridden][password-bug]).
 
 **Additional notes:**
 
-- The Kubernetes cluster is connected to the `gitlab-ee` project using [GitLab's
-  Kubernetes integration][gitlab-k8s-integration]. This basically allows to have
-  a link to the review app directly from the merge request widget.
-- The manual `stop_review` in the `post-cleanup` stage can be used to stop a
-  review app manually, and is also started by GitLab once a branch is deleted
-- [TBD] Review apps are cleaned up regularly using a pipeline schedule that runs
-  the [`scripts/review_apps/automated_cleanup.rb`][automated_cleanup.rb] script
+- The Kubernetes cluster is connected to the `gitlab-{ce,ee}` projects using
+  [GitLab's Kubernetes integration][gitlab-k8s-integration]. This basically
+  allows to have a link to the Review App directly from the merge request
+  widget.
+- If the Review App deployment fails, you can simply retry it (there's no need
+  to run the [`review-stop`][gitlab-ci-yml] job first).
+- The manual [`review-stop`][gitlab-ci-yml] in the `test` stage can be used to
+  stop a Review App manually, and is also started by GitLab once a branch is
+  deleted.
+- Review Apps are cleaned up regularly using a pipeline schedule that runs
+  the [`schedule:review-cleanup`][gitlab-ci-yml] job.
+
+## QA runs
+
+On every [pipeline][gitlab-pipeline] during the `test` stage, the
+`review-qa-smoke` job is automatically started: it runs the smoke QA suite.
+You can also manually start the `review-qa-all`: it runs the full QA suite.
 
-[^1]: We use the `CNG-mirror` project so that the `CNG`, (**C**loud **N**ative **G**itLab), project's registry is
-  not overloaded with a lot of transient Docker images.
-[^2]: Since we're using [the official GitLab Helm chart][helm-chart], this means
-  you get the a dedicated environment for your branch that's very close to what it
-  would look in production
+Note that both jobs first wait for the `review-deploy` job to be finished.
 
 ## Frequently Asked Questions
 
-**Will it be too much to trigger CNG image builds on every test run? This could create thousands of unused docker images.**
+**Isn't it too much to trigger CNG image builds on every test run? This creates
+thousands of unused Docker images.**
 
-  > We have to start somewhere and improve later. If we see this getting out of hand, we will revisit.
+  > We have to start somewhere and improve later. Also, we're using the
+  CNG-mirror project to store these Docker images so that we can just wipe out
+  the registry at some point, and use a new fresh, empty one.
 
-**How big is the Kubernetes cluster?**
+**How big are the Kubernetes clusters (`review-apps-ce` and `review-apps-ee`)?**
 
-  > The cluster is currently setup with a single pool of preemptible
-    nodes, with a minimum of 1 node and a maximum of 30 nodes.
+  > The clusters are currently set up with a single pool of preemptible nodes,
+  with a minimum of 1 node and a maximum of 100 nodes.
 
 **What are the machine running on the cluster?**
 
   > We're currently using `n1-standard-4` (4 vCPUs, 15 GB memory) machines.
 
-**How do we secure this from abuse? Apps are open to the world so we need to find a way to limit it to only us.**
+**How do we secure this from abuse? Apps are open to the world so we need to
+find a way to limit it to only us.**
 
-  > This won't work for forks. We will add a root password to 1password shared vault.
+  > This isn't enabled for forks.
 
-[gitlab-pipeline]: https://gitlab.com/gitlab-org/gitlab-ee/pipelines/29302122
-[review-job]: https://gitlab.com/gitlab-org/gitlab-ee/-/jobs/94294136
+[gitlab-pipeline]: https://gitlab.com/gitlab-org/gitlab-ce/pipelines/35850709
+[review-deploy-job]: https://gitlab.com/gitlab-org/gitlab-ce/-/jobs/118076368
 [cng-mirror]: https://gitlab.com/gitlab-org/build/CNG-mirror
-[cng-pipeline]: https://gitlab.com/gitlab-org/build/CNG-mirror/pipelines/29307727
+[cng-pipeline]: https://gitlab.com/gitlab-org/build/CNG-mirror/pipelines/35883435
 [cng-mirror-registry]: https://gitlab.com/gitlab-org/build/CNG-mirror/container_registry
 [helm-chart]: https://gitlab.com/charts/gitlab/
+[review-apps-ce]: https://console.cloud.google.com/kubernetes/clusters/details/us-central1-a/review-apps-ce?project=gitlab-review-apps
 [review-apps-ee]: https://console.cloud.google.com/kubernetes/clusters/details/us-central1-b/review-apps-ee?project=gitlab-review-apps
 [review-apps.sh]: https://gitlab.com/gitlab-org/gitlab-ee/blob/master/scripts/review_apps/review-apps.sh
 [automated_cleanup.rb]: https://gitlab.com/gitlab-org/gitlab-ee/blob/master/scripts/review_apps/automated_cleanup.rb
-[Auto-DevOps.gitlab-ci.yml]: https://gitlab.com/gitlab-org/gitlab-ci-yml/blob/master/Auto-DevOps.gitlab-ci.yml
+[Auto-DevOps.gitlab-ci.yml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml
+[gitlab-ci-yml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.gitlab-ci.yml
 [gitlab-k8s-integration]: https://docs.gitlab.com/ee/user/project/clusters/index.html
+[password-bug]: https://gitlab.com/gitlab-org/gitlab-ce/issues/53621
 
 ---
 
diff --git a/doc/development/testing_guide/smoke.md b/doc/development/testing_guide/smoke.md
index 3f2843cba6e..3360031c220 100644
--- a/doc/development/testing_guide/smoke.md
+++ b/doc/development/testing_guide/smoke.md
@@ -1,8 +1,9 @@
 # Smoke Tests
 
-It is imperative in any testing suite that we have Smoke Tests.  In short, smoke tests are will run quick sanity
-end-to-end functional tests from GitLab QA and are designed to run against the specified environment to ensure that 
-basic functionality is working.
+It is imperative in any testing suite that we have Smoke Tests. In short, smoke
+tests will run quick sanity end-to-end functional tests from GitLab QA and are
+designed to run against the specified environment to ensure that basic
+functionality is working.
 
 Currently, our suite consists of this basic functionality coverage:
 
@@ -11,6 +12,8 @@ Currently, our suite consists of this basic functionality coverage:
 - Issue Creation
 - Merge Request Creation
 
+Smoke tests have the `:smoke` RSpec metadata.
+
 ---
 
 [Return to Testing documentation](index.md)
diff --git a/doc/development/testing_guide/testing_levels.md b/doc/development/testing_guide/testing_levels.md
index 32ed22ca3ed..a8671fc3aa3 100644
--- a/doc/development/testing_guide/testing_levels.md
+++ b/doc/development/testing_guide/testing_levels.md
@@ -34,7 +34,11 @@ records should use stubs/doubles as much as possible.
 
 Formal definition: https://en.wikipedia.org/wiki/Integration_testing
 
-These kind of tests ensure that individual parts of the application work well together, without the overhead of the actual app environment (i.e. the browser). These tests should assert at the request/response level: status code, headers, body. They're useful to test permissions, redirections, what view is rendered etc.
+These kind of tests ensure that individual parts of the application work well
+together, without the overhead of the actual app environment (i.e. the browser).
+These tests should assert at the request/response level: status code, headers,
+body.
+They're useful to test permissions, redirections, what view is rendered etc.
 
 | Code path | Tests path | Testing engine | Notes |
 | --------- | ---------- | -------------- | ----- |
@@ -67,20 +71,40 @@ run JavaScript tests, so you can either run unit tests (e.g. test a single
 JavaScript method), or integration tests (e.g. test a component that is composed
 of multiple components).
 
-## System tests or feature tests
+## White-box tests at the system level (formerly known as System / Feature tests)
 
-Formal definition: https://en.wikipedia.org/wiki/System_testing.
+Formal definitions:
 
-These kind of tests ensure the application works as expected from a user point
-of view (aka black-box testing). These tests should test a happy path for a
-given page or set of pages, and a test case should be added for any regression
+- https://en.wikipedia.org/wiki/System_testing
+- https://en.wikipedia.org/wiki/White-box_testing
+
+These kind of tests ensure the GitLab *Rails* application (i.e.
+`gitlab-ce`/`gitlab-ee`) works as expected from a *browser* point of view.
+
+Note that:
+
+- knowledge of the internals of the application are still required
+- data needed for the tests are usually created directly using RSpec factories
+- expectations are often set on the database or objects state
+
+These tests should only be used when:
+
+- the functionality/component being tested is small
+- the internal state of the objects/database *needs* to be tested
+- it cannot be tested at a lower level
+
+For instance, to test the breadcrumbs on a given page, writing a system test
+makes sense since it's a small component, which cannot be tested at the unit or
+controller level.
+
+Only test the happy path, but make sure to add a test case for any regression
 that couldn't have been caught at lower levels with better tests (i.e. if a
 regression is found, regression tests should be added at the lowest-level
 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]. |
+| `spec/features/` | [Capybara] + [RSpec] | If your test has the `:js` metadata, the browser driver will be [Poltergeist], otherwise it's using [RackTest]. |
 
 ### Consider **not** writing a system test!
 
@@ -89,7 +113,7 @@ we have enough Unit & Integration tests), we shouldn't need to duplicate their
 thorough testing at the System test level.
 
 It's very easy to add tests, but a lot harder to remove or improve tests, so one
-should take care of not introducing too many (slow and duplicated) specs.
+should take care of not introducing too many (slow and duplicated) tests.
 
 The reasons why we should follow these best practices are as follows:
 
@@ -107,29 +131,33 @@ The reasons why we should follow these best practices are as follows:
 [Poltergeist]: https://github.com/teamcapybara/capybara#poltergeist
 [RackTest]: https://github.com/teamcapybara/capybara#racktest
 
-## Black-box tests or end-to-end tests
+## Black-box tests at the system level, aka end-to-end tests
+
+Formal definitions:
+
+- https://en.wikipedia.org/wiki/System_testing
+- https://en.wikipedia.org/wiki/Black-box_testing
 
 GitLab consists of [multiple pieces] such as [GitLab Shell], [GitLab Workhorse],
 [Gitaly], [GitLab Pages], [GitLab Runner], and GitLab Rails. All theses pieces
 are configured and packaged by [GitLab Omnibus].
 
-[GitLab QA] is a tool that allows to test that all these pieces integrate well
-together by building a Docker image for a given version of GitLab Rails and
-running feature tests (i.e. using Capybara) against it.
+The QA framework and instance-level scenarios are [part of GitLab Rails] so that
+they're always in-sync with the codebase (especially the views).
 
-The actual test scenarios and steps are [part of GitLab Rails] so that they're
-always in-sync with the codebase.
+Note that:
 
-### Smoke tests
-
-Smoke tests are quick tests that may be run at any time (especially after the pre-deployment migrations).
+- knowledge of the internals of the application are not required
+- data needed for the tests can only be created using the GUI or the API
+- expectations can only be made against the browser page and API responses
 
-Much like feature tests - these tests run against the UI and ensure that basic functionality is working.
+Every new feature should come with a [test plan].
 
-> See [Smoke Tests](smoke.md) for more information.
+| Tests path | Testing engine | Notes |
+| ---------- | -------------- | ----- |
+| `qa/qa/specs/features/` | [Capybara] + [RSpec] + Custom QA framework | Tests should be placed under their corresponding [Product category] |
 
-Read a separate document about [end-to-end tests](end_to_end_tests.md) to
-learn more.
+> See [end-to-end tests](end_to_end_tests.md) for more information.
 
 [multiple pieces]: ../architecture.md#components
 [GitLab Shell]: https://gitlab.com/gitlab-org/gitlab-shell
@@ -138,8 +166,29 @@ learn more.
 [GitLab Pages]: https://gitlab.com/gitlab-org/gitlab-pages
 [GitLab Runner]: https://gitlab.com/gitlab-org/gitlab-runner
 [GitLab Omnibus]: https://gitlab.com/gitlab-org/omnibus-gitlab
-[GitLab QA]: https://gitlab.com/gitlab-org/gitlab-qa
 [part of GitLab Rails]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/qa
+[test plan]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/.gitlab/issue_templates/Test%20plan.md
+[Product category]: https://about.gitlab.com/handbook/product/categories/
+
+### Smoke tests
+
+Smoke tests are quick tests that may be run at any time (especially after the
+pre-deployment migrations).
+
+These tests run against the UI and ensure that basic functionality is working.
+
+> See [Smoke Tests](smoke.md) for more information.
+
+### GitLab QA orchestrator
+
+[GitLab QA orchestrator] is a tool that allows to test that all these pieces
+integrate well together by building a Docker image for a given version of GitLab
+Rails and running end-to-end tests (i.e. using Capybara) against it.
+
+Learn more in the [GitLab QA orchestrator README][gitlab-qa-readme].
+
+[GitLab QA orchestrator]: https://gitlab.com/gitlab-org/gitlab-qa
+[gitlab-qa-readme]: https://gitlab.com/gitlab-org/gitlab-qa/tree/master/README.md
 
 ## EE-specific tests
 
diff --git a/doc/development/ui_guide.md b/doc/development/ui_guide.md
index df6ac452300..1e84bf608f4 100644
--- a/doc/development/ui_guide.md
+++ b/doc/development/ui_guide.md
@@ -1,107 +1,5 @@
-# UI Guide for building GitLab
+---
+redirect_to: 'https://design.gitlab.com/'
+---
 
-## GitLab UI development kit
-
-We created a page inside GitLab where you can check commonly used html and css elements.
-
-When you run GitLab instance locally - just visit http://localhost:3000/help/ui page to see UI examples
-you can use during GitLab development.
-
-## Design repository
-
-All design files are stored in the [gitlab-design](https://gitlab.com/gitlab-org/gitlab-design)
-repository and maintained by GitLab UX designers.
-
-## Navigation
-
-GitLab's layout contains 2 sections: the left sidebar and the content. The left sidebar contains a static navigation menu.
-This menu will be visible regardless of what page you visit.
-The content section contains a header and the content itself. The header describes the current GitLab page and what navigation is
-available to the user in this area. Depending on the area (project, group, profile setting) the header name and navigation may change. For example, when the user visits one of the
-project pages the header will contain the project's name and navigation for that project. When the user visits a group page it will contain the group's name and navigation related to this group.
-
-You can see a visual representation of the navigation in GitLab in the GitLab Product Map, which is located in the [Design Repository][gitlab-map-graffle]
-along with [PDF][gitlab-map-pdf] and [PNG][gitlab-map-png] exports.
-
-
-### Adding new tab to header navigation
-
-We try to keep the amount of tabs in the header navigation between 5 and 10 so that it fits on a typical laptop screen. We also try not to confuse the user with too many options. Ideally each
-tab should represent separate functionality. Everything related to the issue
-tracker should be under the 'Issues' tab while everything related to the wiki should
-be under 'Wiki' tab and so on and so forth.
-When adding a new tab to the header don't use more than 2 words for text in the link.
-We want to keep links short and easy to remember and fit all of them in the small screen.
-
-## Mobile screen size
-
-We want GitLab to work well on small mobile screens as well. Size limitations make it is impossible to fit everything on a mobile screen. In this case it is OK to hide
-part of the UI for smaller resolutions in favor of a better user experience.
-However core functionality like browsing files, creating issues, writing comments, should
-be available on all resolutions.
-
-## Icons
-
-* `trash` icon for button or link that does destructive action like removing
-information from database or file system
-* `x` icon for closing/hiding UI element. For example close modal window
-* `pencil` icon for edit button or link
-* `eye` icon for subscribe action
-* `rss` for rss/atom feed
-* `plus` for link or dropdown that lead to page where you create new object (For example new issue page)
-
-### SVGs
-
-When exporting SVGs, be sure to follow the following guidelines:
-
-1. Convert all strokes to outlines.
-2. Use pathfinder tools to combine overlapping paths and create compound paths.
-3. SVGs that are limited to one color should be exported without a fill color so the color can be set using CSS.
-4. Ensure that exported SVGs have been run through an [SVG cleaner](https://github.com/RazrFalcon/SVGCleaner) to remove unused elements and attributes.
-
-You can open your svg in a text editor to ensure that it is clean. 
-Incorrect files will look like this:
-
-```xml
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<svg width="16px" height="17px" viewBox="0 0 16 17" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
-    <!-- Generator: Sketch 3.7.2 (28276) - http://www.bohemiancoding.com/sketch -->
-    <title>Group</title>
-    <desc>Created with Sketch.</desc>
-    <defs></defs>
-    <g id="Page-1" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
-        <g id="Group" fill="#7E7C7C">
-            <path d="M15.1111,1 L0.8891,1 C0.3981,1 0.0001,1.446 0.0001,1.996 L0.0001,15.945 C0.0001,16.495 0.3981,16.941 0.8891,16.941 L15.1111,16.941 C15.6021,16.941 16.0001,16.495 16.0001,15.945 L16.0001,1.996 C16.0001,1.446 15.6021,1 15.1111,1 L15.1111,1 L15.1111,1 Z M14.0001,6.0002 L14.0001,14.949 L2.0001,14.949 L2.0001,6.0002 L14.0001,6.0002 Z M14.0001,4.0002 L14.0001,2.993 L2.0001,2.993 L2.0001,4.0002 L14.0001,4.0002 Z" id="Combined-Shape"></path>
-            <polygon id="Fill-11" points="3 2.0002 5 2.0002 5 0.0002 3 0.0002"></polygon>
-            <polygon id="Fill-16" points="11 2.0002 13 2.0002 13 0.0002 11 0.0002"></polygon>
-            <path d="M5.37709616,11.5511984 L6.92309616,12.7821984 C7.35112915,13.123019 7.97359761,13.0565604 8.32002627,12.6330535 L10.7740263,9.63305349 C11.1237073,9.20557058 11.0606364,8.57555475 10.6331535,8.22587373 C10.2056706,7.87619272 9.57565475,7.93926361 9.22597373,8.36674651 L6.77197373,11.3667465 L8.16890384,11.2176016 L6.62290384,9.98660159 C6.19085236,9.6425813 5.56172188,9.71394467 5.21770159,10.1459962 C4.8736813,10.5780476 4.94504467,11.2071781 5.37709616,11.5511984 L5.37709616,11.5511984 Z" id="Stroke-21"></path>
-        </g>
-    </g>
-</svg>
-```
-
-Correct file will look like this:
-
-```xml
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 17" enable-background="new 0 0 16 17"><path d="m15.1 1h-2.1v-1h-2v1h-6v-1h-2v1h-2.1c-.5 0-.9.5-.9 1v14c0 .6.4 1 .9 1h14.2c.5 0 .9-.4.9-1v-14c0-.5-.4-1-.9-1m-1.1 14h-12v-9h12v9m0-11h-12v-1h12v1"/><path d="m5.4 11.6l1.5 1.2c.4.3 1.1.3 1.4-.1l2.5-3c.3-.4.3-1.1-.1-1.4-.5-.4-1.1-.3-1.5.1l-1.8 2.2-.8-.6c-.4-.3-1.1-.3-1.4.2-.3.4-.3 1 .2 1.4"/></svg>
-```
-
-
-## Buttons
-
-* Button should contain icon or text. Exceptions should be approved by UX designer.
-* Use red button for destructive actions (not revertable). For example removing issue.
-* Use green or blue button for primary action. Primary button should be only one.
-Do not use both green and blue button in one form.
-* For all other cases use default white button.
-* Text button should have only first word capitalized. So should be "Create issue" instead of "Create Issue"
-
-## Counts
-
-* Always use the [`number_with_delimiter`][number_with_delimiter] helper to
-  display counts in the UI.
-
-[number_with_delimiter]: http://api.rubyonrails.org/classes/ActionView/Helpers/NumberHelper.html#method-i-number_with_delimiter
-[gitlab-map-graffle]: https://gitlab.com/gitlab-org/gitlab-design/blob/master/production/resources/gitlab-map.graffle
-[gitlab-map-pdf]: https://gitlab.com/gitlab-org/gitlab-design/raw/master/production/resources/gitlab-map.pdf
-[gitlab-map-png]: https://gitlab.com/gitlab-org/gitlab-design/raw/master/production/resources/gitlab-map.png
+The content of this document was moved into the [GitLab Design System](https://design.gitlab.com/).
diff --git a/doc/development/utilities.md b/doc/development/utilities.md
index 0d074a3ef05..e5466ae8914 100644
--- a/doc/development/utilities.md
+++ b/doc/development/utilities.md
@@ -171,8 +171,8 @@ class Commit
   extend Gitlab::Cache::RequestCache
 
   def author
-    User.find_by_any_email(author_email.downcase)
+    User.find_by_any_email(author_email)
   end
-  request_cache(:author) { author_email.downcase }
+  request_cache(:author) { author_email }
 end
 ```
diff --git a/doc/development/ux_guide/animation.md b/doc/development/ux_guide/animation.md
index 797390a6845..583ff19bc69 100644
--- a/doc/development/ux_guide/animation.md
+++ b/doc/development/ux_guide/animation.md
@@ -1,65 +1,5 @@
-# Animation
+---
+redirect_to: 'https://design.gitlab.com/foundations/motion'
+---
 
-Motion is a tool to help convey important relationships, changes or transitions between elements. It should be used sparingly and intentionally, highlighting the right elements at the right moment.
-
-## Timings
-
-The longer distance an object travel, the timing should be longer for the animation. However, when in doubt, we should avoid large, full screen animations.
-
-Subtle animations, or objects leaving the screen should take **100-200 milliseconds**. Objects entering the screen, or motion we want to use to direct user attention can take between **200-400 milliseconds**. We should avoid animations of longer than 400 milliseconds as they will make the experience appear sluggish. If a specific animation feels like it will need more than 400 milliseconds, revisit the animation to see if there is a simpler, easier, shorter animation to implement.
-
-## Easing
-
-Easing specifies the rate of change of a parameter over time (see [easings.net](http://easings.net/)). Adding an easing curve will make the motion feel more natural. Being consistent with the easing curves will make the whole experience feel more cohesive and connected.
-
-* When an object is entering the screen, or transforming the scale, position, or shape, use the **easeOutQuint** curve (`cubic-bezier(0.23, 1, 0.32, 1)`)
-* When an object is leaving the screen, or transforming the opacity or color, no easing curve is needed. It shouldn't _slow down_ as it is exiting the screen, as that draws attention on the leaving object, where we don't want it. Adding easing to opacity and color transitions will make the motion appear less smooth. Therefore, for these cases, motion should just be **linear**.
-
-## Types of animations
-
-### Hover
-
-Interactive elements (links, buttons, etc.) should have a hover state. A subtle animation for this transition adds a polished feel. We should target a `100ms - 150ms linear` transition for a color hover effect.
-
-View the [interactive example](http://codepen.io/awhildy/full/GNyEvM/) here.
-
-![Hover animation](img/animation-hover.gif)
-
-### Dropdowns
-
-The dropdown menu should feel like it is appearing from the triggering element. Combining a position shift `400ms cubic-bezier(0.23, 1, 0.32, 1)` with an opacity animation `200ms linear` on the second half of the motion achieves this affect.
-
-View the [interactive example](http://codepen.io/awhildy/full/jVLJpb/) here.
-
-![Dropdown animation](img/animation-dropdown.gif)
-
-### Quick update
-
-When information is updating in place, a quick, subtle animation is needed. The previous content should cut out, and the new content should have a quick, `200ms linear` fade in.
-
-![Quick update animation](img/animation-quickupdate.gif)
-
-### Skeleton loading
-
-Skeleton loading is explained in the [component section](components.html#skeleton-loading) of the UX guide. It includes a horizontally pulsating animation that shows motion as if it's growing. It's timing is a slower `linear 1s`.
-
-![Skeleton loading animation](img/skeleton-loading.gif)
-
-### Moving transitions
-
-When elements move on screen, there should be a quick animation so it is clear to users what moved where. The timing of this animation differs based on the amount of movement and change. Consider animations between `200ms` and `400ms`.
-
-#### Shifting elements on reorder
-An example of a moving transition is when elements have to move out of the way when you drag an element.
-
-View the [interactive example](http://codepen.io/awhildy/full/ALyKPE/) here.
-
-![Reorder animation](img/animation-reorder.gif)
-
-#### Autoscroll the page
-
-Another example of a moving transition is when you have to autoscroll the page to keep an active element visible.
-
-View the [interactive example](http://codepen.io/awhildy/full/PbxgVo/) here.
-
-![Autoscroll animation](img/animation-autoscroll.gif)
+The content of this document was moved into the [GitLab Design System](https://design.gitlab.com).
diff --git a/doc/development/ux_guide/basics.md b/doc/development/ux_guide/basics.md
index e215026bcca..1e84bf608f4 100644
--- a/doc/development/ux_guide/basics.md
+++ b/doc/development/ux_guide/basics.md
@@ -1,82 +1,5 @@
-# Basics
-
-## Contents
-* [Responsive](#responsive)
-* [Typography](#typography)
-* [Icons](#icons)
-* [Color](#color)
-* [Cursors](#cursors)
-
----
-
-## Responsive
-GitLab is a responsive experience that works well across all screen sizes, from mobile devices to large monitors. In order to provide a great user experience, the core functionality (browsing files, creating issues, writing comments, etc.) must be available at all resolutions. However, due to size limitations, some secondary functionality may be hidden on smaller screens. Please keep this functionality limited to rare actions that aren't expected to be needed on small devices.
-
----
-
-## Typography
-### Primary typeface
-GitLab's main typeface used throughout the UI is **Source Sans Pro**. We support both the bold and regular weight.
-
-![Source Sans Pro sample](img/sourcesanspro-sample.png)
-
-
-### Monospace typeface
-This is the typeface used for code blocks and references to commits, branches, and tags (`.commit-sha` or `.ref-name`). GitLab uses the OS default font.
-- **Menlo** (Mac)
-- **Consolas** (Windows)
-- **Liberation Mono** (Linux)
-
-![Monospace font sample](img/monospacefont-sample.png)
-
----
-
-## Icons
-
-GitLab has a strong, unique personality. When you look at any screen, you should know immediately that it is GitLab. 
-Iconography is a powerful visual cue to the user and is a great way for us to reflect our particular sense of style.
-
-- **Standard size:** 16px * 16px
-- **Border thickness:** 2px
-- **Border radius:** 3px
-
-![Icon sampler](img/icon-spec.png)
-
-> TODO: List all icons, proper usage, hover, and active states.
-
 ---
-
-## Color
-
-| | State | Action |
-| :------: | :------- | :------- |
-| ![Blue](img/color-blue.png) | Primary and active (such as the current tab) | Organizational, managing, and retry commands|
-| ![Green](img/color-green.png) | Opened | Create new objects |
-| ![Orange](img/color-orange.png) | Warning | Non destructive action |
-| ![Red](img/color-red.png) | Closed | Delete and other destructive commands |
-| ![Grey](img/color-grey.png) | Neutral | Neutral secondary commands |
-
-### Text colors
-
-|||
-| :---: | :--- |
-| ![Text primary](img/color-textprimary.png) | Used for primary body text, such as issue description and comment |
-| ![Text secondary](img/color-textsecondary.png) | Used for secondary body text, such as username and date |
-
-> TODO: Establish a perspective for color in terms of our personality and rationalize with Marketing usage.
-
+redirect_to: 'https://design.gitlab.com/'
 ---
 
-## Cursors
-The mouse cursor is key in helping users understand how to interact with elements on the screen.
-
-| | |
-| :------: | :------- |
-| ![Default cursor](img/cursors-default.png) | Default cursor |
-| ![Pointer cursor](img/cursors-pointer.png) | Pointer cursor: used to indicate that you can click on an element to invoke a command or navigate, such as links and buttons |
-| ![Move cursor](img/cursors-move.png) | Move cursor: used to indicate that you can move an element around on the screen |
-| ![Pan opened cursor](img/cursors-panopened.png) | Pan cursor (opened): indicates that you can grab and move the entire canvas, affecting what is seen in the view port. |
-| ![Pan closed cursor](img/cursors-panclosed.png) | Pan cursor (closed): indicates that you are actively panning the canvas. |
-| ![I-beam cursor](img/cursors-ibeam.png) | I-beam cursor: indicates that this is either text that you can select and copy, or a text field that you can click into to enter text. |
-
-
+The content of this document was moved into the [GitLab Design System](https://design.gitlab.com/).
diff --git a/doc/development/ux_guide/components.md b/doc/development/ux_guide/components.md
index 4a3b3125f59..1e84bf608f4 100644
--- a/doc/development/ux_guide/components.md
+++ b/doc/development/ux_guide/components.md
@@ -1,387 +1,5 @@
-# Components
-
-## Contents
-* [Tooltips](#tooltips)
-* [Anchor links](#anchor-links)
-* [Buttons](#buttons)
-* [Dropdowns](#dropdowns)
-* [Counts](#counts)
-* [Lists](#lists)
-* [Tables](#tables)
-* [Blocks](#blocks)
-* [Panels](#panels)
-* [Modals](#modals)
-* [Alerts](#alerts)
-* [Forms](#forms)
-* [Search box](#search-box)
-* [File holders](#file-holders)
-* [Data formats](#data-formats)
-
----
-
-## Tooltips
-Tooltips identify elements or provide additional, useful information about the referring elements. Tooltips are different from ALT-attributes, which are intended primarily for static images. Tooltips are summoned by:
-
-* Hovering over an element with a cursor
-* Focusing on an element with a keyboard (usually the tab key)
-* Upon touch
-
-### Usage
-A tooltip should be used:
-* When there isn’t enough space to show the information
-* When it isn’t critical for the user to see the information
-* For icons that don’t have a label
-
-Tooltips shouldn’t repeat information that is shown near the referring element. However, they can show the same data in a different format (e.g. date or timestamps).
-
-![Tooltip usage](img/tooltip-usage.png)
-
-### Placement
-By default, tooltips should be placed below the referring element. However, if there isn’t enough space in the viewport, the tooltip should be moved to the side as needed.
-
-![Tooltip placement location](img/tooltip-placement.png)
-
----
-
-## Popovers
-
-Popovers provide additional, useful, unique information about the referring elements and can provide one or multiple actionable elements. They inform the user of additional information within the context of their original view, but without forcing the user to act upon it like a modal. Popovers are different from tooltips, which do not provide rich markup and actionable items. A popover can contain a header section with a different background color.
-
-Popovers are summoned:
-
-* Upon hover or touch on an element
-
-### Usage
-A popover should be used:
-* When you don't want to let the user lose context, but still want to provide additional useful unique information about referring elements
-* When it isn’t critical for the user to act upon the information
-* When you want to give a user a summary of extended information and the option to switch context if they want to dive in deeper.
-
-### Styling
-
-A popover can contain a header section with a different background color if that improves readability and separation of content within.
-
-![Popover usage](img/popover-placement-below.png)
-
-This example shows two sections, where each section includes an actionable element. The first section shows a summary of the content shown when clicking the "read more" link. With this information the user can decide to dive deeper or start their GitLab Enterprise Edition trial immediately.
-
-### Placement
-By default, tooltips should be placed below the referring element. However, if there isn’t enough space in the viewport or it blocks related content, the tooltip should be moved to the side or above as needed.
-
-![Tooltip placement location](img/popover-placement-above.png)
-
-In this example we let the user know more about the setting they are deciding over, without loosing context. If they want to know even more they can do so, but with the expectation of opening that content in a new view.
-
----
-
-## Anchor links
-
-Anchor links are used for navigational actions and lone, secondary commands (such as 'Reset filters' on the Issues List) when deemed appropriate by the UX team.
-
-### States
-
-#### Rest
-
-Primary links are blue in their rest state. Secondary links (such as the time stamp on comments) are a neutral gray color in rest. Details on the main GitLab navigation links can be found on the [features](features.md#navigation) page.
-
-#### Hover
-
-On hover, an underline should be added and the color should change. Both the primary and secondary link should become the darker blue color on hover.
-
-#### Focus
-
-The focus state should match the hover state.
-
-![Anchor link states ](img/components-anchorlinks.png)
-
----
-
-## Buttons
-
-Buttons communicate the command that will occur when the user clicks on them.
-
-### Types
-
-#### Primary
-Primary buttons communicate the main call to action. There should only be one call to action in any given experience. Visually, primary buttons are conveyed with a full background fill
-
-![Primary button example](img/button-primary.png)
-
-#### Secondary
-Secondary buttons are for alternative commands. They should be conveyed by a button with a stroke, and no background fill.
-
-![Secondary button example](img/button-secondary.png)
-
-### Icon and text treatment
-Text should be in sentence case, where only the first word is capitalized. "Create issue" is correct, not "Create Issue". Buttons should only contain an icon or a text, not both.
-
-> TODO: Rationalize this. Ensure that we still believe this.
-
-### Colors
-The default color treatment is the white/grey button. Follow the guidance on the [basics](basics.md#color) page to add meaningful color to a button.
-
-### Secondary states
-
-Primary buttons darken the color of their background and border for hover, focus and active states. An inner shadow is added to the active state to denote the button being pressed.
-
-| Values | Info | Success | Warning | Danger |
-| :------ | :------: | :------: | :------: | :------: |
-| Background: `$color-light` <br> Border: `$border-color-light` | ![](img/button-info--resting.png) | ![](img/button-success--resting.png) | ![](img/button-warning--resting.png) | ![](img/button-danger--resting.png) |
-| Background: `$color-normal` <br> Border: `$border-color-normal` | ![](img/button-info--hover.png) | ![](img/button-success--hover.png) | ![](img/button-warning--hover.png) | ![](img/button-danger--hover.png) |
-| Background: `$color-dark` <br> Border: `$border-color-dark` | ![](img/button-info--active.png) | ![](img/button-success--active.png) | ![](img/button-warning--active.png) | ![](img/button-danger--active.png) |
-
-Since secondary buttons only have a border on their resting state, their hover and focus states add a background color, which gets darkened on active.
-
-| Values | Success Secondary | Close | Spam |
-| :------ | :------: | :------: | :------: |
-| Font: `$border-color-light` <br> Border: `$border-color-light` | ![](img/button-success-secondary--resting.png) | ![](img/button-close--resting.png) | ![](img/button-spam--resting.png) |
-| Background: `$color-light` <br> Border: `$border-color-light` | ![](img/button-success-secondary--hover.png) | ![](img/button-close--hover.png) | ![](img/button-spam--hover.png) |
-| Background: `$color-normal` <br> Border: `$border-color-normal` | ![](img/button-success-secondary--active.png) | ![](img/button-close--active.png) | ![](img/button-spam--active.png) |
-
-### Placement
-
-When there are a group of buttons in a dialog or a form, we need to be consistent with the placement.
-
-#### Dismissive actions on the left
-The dismissive action returns the user to the previous state.
-
-> Example: Cancel
-
-#### Affirmative actions on the right
-Affirmative actions continue to progress towards the user goal that triggered the dialog or form.
-
-> Example: Submit, Ok, Delete
-
----
-
-
-## Dropdowns
-
-Dropdowns are used to allow users to choose one (or many) options from a list of options. If this list of options is more 20, there should generally be a way to search through and filter the options (see the complex filter dropdowns below.)
-
-> TODO: Will update this section when the new filters UI is implemented.
-
-![Dropdown states](img/components-dropdown.png)
-
-### Max size
-
-The max height for dropdowns should target **10-15** single line items, or **7-10** multi-line items. If the height of the dropdown is too large, the list becomes very hard to parse and it is easy to visually lose track of the item you are looking for. Usability also suffers as more mouse movement is required, and you have a larger area in which you hijack the scroll away from the page level. While it may initially seem counterintuitive to not show as many items as you can, it is actually quicker and easier to process the information when it is cropped at a reasonable height.
-
----
-
-## Counts
-
-A count element is used in navigation contexts where it is helpful to indicate the count, or number of items, in a list. Always use the [`number_with_delimiter`][number_with_delimiter] helper to display counts in the UI.
-
-![Counts example](img/components-counts.png)
-
-[number_with_delimiter]: http://api.rubyonrails.org/classes/ActionView/Helpers/NumberHelper.html#method-i-number_with_delimiter
-
----
-
-## Lists
-
-Lists are used where ever there is a single column of information to display. Ths [issues list](https://gitlab.com/gitlab-org/gitlab-ce/issues) is an example of an important list in the GitLab UI.
-
-### Types
-
-Simple list using .content-list
-
-![Simple list](img/components-simplelist.png)
-
-List with avatar, title and description using .content-list
-
-![List with avatar](img/components-listwithavatar.png)
-
-List with hover effect .content-list
-
-![List with hover effect](img/components-listwithhover.png)
-
-List inside panel
-
-![List inside panel](img/components-listinsidepanel.png)
-
----
-
-## Tables
-
-When the information is too complex for a list, with multiple columns of information, a table can be used. For example, the [pipelines page](https://gitlab.com/gitlab-org/gitlab-ce/pipelines) uses a table.
-
-![Table](img/components-table.png)
-
----
-
-## Blocks
-
-Blocks are a way to group related information.
-
-### Types
-
-#### Content blocks
-
-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)
-
-#### Row content blocks
-
-A background color can be added to this blocks. For example, items in the [issue list](https://gitlab.com/gitlab-org/gitlab-ce/issues) have a green background if they were created recently. Below is an example of a gray content block with side padding using `.row-content-block`.
-
-![Row content block](img/components-rowcontentblock.png)
-
-#### Cover blocks
-Cover blocks are generally used to create a heading element for a page, such as a new project, or a user profile page. Below is a cover block (`.cover-block`) for the profile page with an avatar, name and description.
-
-![Cover block](img/components-coverblock.png)
-
----
-
-## Skeleton loading
-
-Skeleton loading is a way to convey to the user what kind of content is currently being loaded. It's a paradigm with which content can independently and asynchronously be loaded, while still adhering to the structure and look of the completely loaded view.
-
-### Requirements
-
-* A skeleton should represent an organism in a recognisable way
-* Atom elements within organisms (for reference see this article on [atomic design methodology](http://atomicdesign.bradfrost.com/chapter-2/)) may be represented in a maximum of 3 repetitions, if applicable.
-* Skeletons should only be presented in grayscale using the HEX colors: `#fafafa` or `#ffffff` (except for shadows)
-* Animate the grey atoms in a pulsating way to show motion, as if "loading". The pulse animation transitions colors horizontally from left to right, starting with `#f2f2f2` to `#fafafa`.
-
-![Skeleton loading animation](img/skeleton-loading.gif)
-
-### Usage
-
-Skeleton loading can replace any existing UI elements for the period in which they are loaded and should aim for maintaining a similar structure visually.
-
----
-
-## Modals
-
-Modals are only used for having a conversation and confirmation with the user. The user is not able to access the features on the main page until closing the modal.
-
-### Usage
-
-* When the action is irreversible, modals provide the details and confirm with the user before they take an advanced action.
-* When the action will affect privacy or authorization, modals provide advanced information and confirm with the user.
-
-### Style
-
-* Modals contain the header, body, and actions.
-  * **Header(1):** The header title is a question instead of a descriptive phrase.
-  * **Body(2):** The content in body should never be ambiguous and unclear. It provides specific information.
-  * **Actions(3):** Contains an affirmative action, a dismissive action, and an extra action. The order of actions from left to right: Dismissive action → Extra action → Affirmative action
-* Confirmations regarding labels should keep labeling styling.
-* References to commits, branches, and tags should be **monospaced**.
-
-![layout-modal](img/modals-layout-for-modals.png)
-
-### Placement
-
-* Modals should always be the center of the screen horizontally and be positioned **72px** from the top.
-
-| 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) | ![special-confirmation](img/modals-special-confimation-dialog.png) |
-
-> TODO: Special case for modal.
-
----
-
-## Panels
-
-> TODO: Catalog how we are currently using panels and rationalize how they relate to alerts
-
-![Panels](img/components-panels.png)
-
----
-
-## Alerts
-
-> TODO: Catalog how we are currently using alerts
-
-![Alerts](img/components-alerts.png)
-
 ---
-
-## Forms
-
-There are two options shown below regarding the positioning of labels in forms. Both are options to consider based on context and available size. However, it is important to have a consistent treatment of labels in the same form.
-
-### Types
-
-#### Labels stack vertically
-
-Form (`form`) with label rendered above input.
-
-![Vertical form](img/components-verticalform.png)
-
-#### Labels side-by-side
-
-Horizontal form (`form.horizontal-form`) with label rendered inline with input.
-
-![Horizontal form](img/components-horizontalform.png)
-
+redirect_to: 'https://design.gitlab.com/'
 ---
 
-## Search box
-
-Search boxes across GitLab have a consistent rest, active and text entered state. When text isn't entered in the box, there should be a magnifying glass right aligned with the input field. When text is entered, the magnifying glass should become a x, allowing users to clear their text.
-
-![Search box](img/components-searchbox.png)
-
-If needed, we indicate the scope of the search in the search box.
-
-![Scoped Search box](img/components-searchboxscoped.png)
-
----
-
-## File holders
-A file holder (`.file-holder`) is used to show the contents of a file inline on a page of GitLab.
-
-![File Holder component](img/components-fileholder.png)
-
----
-
-## Data formats
-
-### Dates
-
-#### Exact
-
-Format for exacts dates should be ‘Mon DD, YYYY’, such as the examples below.
-
-![Exact date](img/components-dateexact.png)
-
-#### Relative
-
-This format relates how long since an action has occurred. The exact date can be shown as a tooltip on hover.
-
-![Relative date](img/components-daterelative.png)
-
-### References
-
-Referencing GitLab items depends on a symbol for each type of item. Typing that symbol will invoke a dropdown that allows you to search for and autocomplete the item you were looking for. References are shown as [links](#links) in context, and hovering on them shows the full title or name of the item.
-
-![Hovering on a reference](img/components-referencehover.png)
-
-#### `%` Milestones
-
-![Milestone reference](img/components-referencemilestone.png)
-
-#### `#` Issues
-
-![Issue reference](img/components-referenceissues.png)
-
-#### `!` Merge Requests
-
-![Merge request reference](img/components-referencemrs.png)
-
-#### `~` Labels
-
-![Labels reference](img/components-referencelabels.png)
-
-#### `@` People
-
-![People reference](img/components-referencepeople.png)
-
-> TODO: Open issue: Some commit references use monospace fonts, but others don't. Need to standardize this.
+The content of this document was moved into the [GitLab Design System](https://design.gitlab.com/).
diff --git a/doc/development/ux_guide/copy.md b/doc/development/ux_guide/copy.md
index d5afa544372..1e84bf608f4 100644
--- a/doc/development/ux_guide/copy.md
+++ b/doc/development/ux_guide/copy.md
@@ -1,198 +1,5 @@
-# Copy

-

-The copy for GitLab is clear and direct. We strike a clear balance between professional and friendly. We can empathesize with users (such as celebrating completing all Todos), and remain respectful of the importance of the work. We are that trusted, friendly coworker that is helpful and understanding.

-

-The copy and messaging is a core part of the experience of GitLab and the conversation with our users. Follow the below conventions throughout GitLab.

-

-Portions of this page are inspired by work found in the [Material Design guidelines][material design].

-

->**Note:**

-We are currently inconsistent with this guidance. Images below are created to illustrate the point. As this guidance is refined, we will ensure that our experiences align.

-

-## Contents

-* [Brevity](#brevity)

-* [Capitalization and punctuation](#capitalization-and-punctuation)

-* [Terminology](#terminology)

-

----

-

-## Brevity

-Users will skim content, rather than read text carefully.

-When familiar with a web app, users rely on muscle memory, and may read even less when moving quickly.

-A good experience should quickly orient a user, regardless of their experience, to the purpose of the current screen. This should happen without the user having to consciously read long strings of text.

-In general, text is burdensome and adds cognitive load. This is especially pronounced in a powerful productivity tool such as GitLab.

-We should _not_ rely on words as a crutch to explain the purpose of a screen.

-The current navigation and composition of the elements on the screen should get the user 95% there, with the remaining 5% being specific elements such as text.

-This means that, as a rule, copy should be very short. A long message or label is a red flag hinting at design that needs improvement.

-

->**Example:**

-Use `Add` instead of `Add issue` as a button label.

-Preferably use context and placement of controls to make it obvious what clicking on them will do.

-

----

-

-## Capitalization and punctuation

-

-### Case

-Use sentence case for titles, headings, labels, menu items, and buttons. Use title case when referring to [features][features] or [products][products]. Note that some features are also objects (e.g. “Merge Requests” and “merge requests”).

-

-| :white_check_mark: Do | :no_entry_sign: Don’t |

-| --- | --- |

-| Add issues to the Issue Board feature in GitLab Hosted | Add Issues To The Issue Board Feature In GitLab Hosted |

-

-### Avoid periods

-Avoid using periods in solitary sentences in these elements:

-

-* Labels

-* Hover text

-* Bulleted lists

-* Modal body text

-

-Periods should be used for:

-

-* Lists or modals with multiple sentences

-* Any sentence followed by a link

-

-| :white_check_mark: **Do** place periods after sentences followed by a link | :no_entry_sign: **Don’t** place periods after a link if it‘s not followed by a sentence |

-| --- | --- |

-| Mention someone to notify them. [Learn more](#) | Mention someone to notify them. [Learn more](#). |

-

-| :white_check_mark: **Do** skip periods after solo sentences of body text | :no_entry_sign: **Don’t** place periods after body text if there is only a single sentence |

-| --- | --- |

-| To see the available commands, enter `/gitlab help` | To see the available commands, enter `/gitlab help`. |

-

-### Use contractions

-Don’t make a sentence harder to understand just to follow this rule. For example, “do not” can give more emphasis than “don’t” when needed.

-

-| :white_check_mark: Do | :no_entry_sign: Don’t |

-| --- | --- |

-| it’s, can’t, wouldn’t, you’re, you’ve, haven’t, don’t | it is, cannot, would not, it’ll, should’ve |

-

-### Use numerals for numbers

-Use “1, 2, 3” instead of “one, two, three” for numbers. One exception is when mixing uses of numbers, such as “Enter two 3s.”

-

-| :white_check_mark: Do | :no_entry_sign: Don’t |

-| --- | --- |

-| 3 new commits | Three new commits |

-

-### Punctuation

-Omit punctuation after phrases and labels to create a cleaner and more readable interface. Use punctuation to add clarity or be grammatically correct.

-

-| Punctuation mark | Copy and paste | HTML entity | Unicode | Mac shortcut | Windows shortcut | Description |

-|---|---|---|---|---|---|---|

-| Period | **.** | | | | | Omit for single sentences in affordances like labels, hover text, bulleted lists, and modal body text.<br><br>Use in lists or modals with multiple sentences, and any sentence followed by a link or inline code.<br><br>Place inside quotation marks unless you’re telling the reader what to enter and it’s ambiguous whether to include the period. |

-| Comma | **,** | | | | | Place inside quotation marks.<br><br>Use a [serial comma][serial comma] in lists of three or more terms. |

-| Exclamation point | **!** | | | | | Avoid exclamation points as they tend to come across as shouting. Some exceptions include greetings or congratulatory messages. |

-| Colon | **:** | `&#58;` | `\u003A` | | | Omit from labels, for example, in the labels for fields in a form. |

-| Apostrophe | **’** | `&rsquo;` | `\u2019` | <kbd>⌥ Option</kbd>+<kbd>⇧ Shift</kbd>+<kbd>]</kbd> | <kbd>Alt</kbd>+<kbd>0 1 4 6</kbd> | Use for contractions (I’m, you’re, ’89) and to show possession.<br><br>To show possession, add an *’s* to all singular common nouns and names, even if they already end in an *s*: “Look into this worker process’s log.” For singular proper names ending in *s*, use only an apostrophe: “James’ commits.” For plurals of a single letter, add an *’s*: “Dot your i’s and cross your t’s.”<br><br>Omit for decades or acronyms: “the 1990s”, “MRs.” |

-| Quotation marks | **“**<br><br>**”**<br><br>**‘**<br><br>**’** | `&ldquo;`<br><br>`&rdquo;`<br><br>`&lsquo;`<br><br>`&rsquo;` | `\u201C`<br><br>`\u201D`<br><br>`\u2018`<br><br>`\u2019` | <kbd>⌥ Option</kbd>+<kbd>[</kbd><br><br><kbd>⌥ Option</kbd>+<kbd>⇧ Shift</kbd>+<kbd>[</kbd><br><br><kbd>⌥ Option</kbd>+<kbd>]</kbd><br><br><kbd>⌥ Option</kbd>+<kbd>⇧ Shift</kbd>+<kbd>]</kbd> | <kbd>Alt</kbd>+<kbd>0 1 4 7</kbd><br><br><kbd>Alt</kbd>+<kbd>0 1 4 8</kbd><br><br><kbd>Alt</kbd>+<kbd>0 1 4 5</kbd><br><br><kbd>Alt</kbd>+<kbd>0 1 4 6</kbd> | Use proper quotation marks (also known as smart quotes, curly quotes, or typographer’s quotes) for quotes. Single quotation marks are used for quotes inside of quotes.<br><br>The right single quotation mark symbol is also used for apostrophes.<br><br>Don’t use primes, straight quotes, or free-standing accents for quotation marks. |

-| Primes | **′**<br><br>**″** | `&prime;`<br><br>`&Prime;` | `\u2032`<br><br>`\u2033` | | <kbd>Alt</kbd>+<kbd>8 2 4 2</kbd><br><br><kbd>Alt</kbd>+<kbd>8 2 4 3</kbd> | Use prime (′) only in abbreviations for feet, arcminutes, and minutes: 3° 15′<br><br>Use double-prime (″) only in abbreviations for inches, arcseconds, and seconds: 3° 15′ 35″<br><br>Don’t use quotation marks, straight quotes, or free-standing accents for primes. |

-| Straight quotes and accents | **"**<br><br>**'**<br><br>**`**<br><br>**´** | `&quot;`<br><br>`&#39;`<br><br>`&#96;`<br><br>`&acute;` | `\u0022`<br><br>`\u0027`<br><br>`\u0060`<br><br>`\u00B4` | | | Don’t use straight quotes or free-standing accents for primes or quotation marks.<br><br>Proper typography never uses straight quotes. They are left over from the age of typewriters and their only modern use is for code. |

-| Ellipsis | **…** | `&hellip;` | | <kbd>⌥ Option</kbd>+<kbd>;</kbd> | <kbd>Alt</kbd>+<kbd>0 1 3 3</kbd> | Use to indicate an action in progress (“Downloading…”) or incomplete or truncated text. No space before the ellipsis.<br><br>Omit from menu items or buttons that open a modal or start some other process. |

-| Chevrons | **«**<br><br>**»**<br><br>**‹**<br><br>**›**<br><br>**<**<br><br>**>** | `&#171;`<br><br>`&#187;`<br><br>`&#8249;`<br><br>`&#8250;`<br><br>`&lt;`<br><br>`&gt;` | `\u00AB`<br><br>`\u00BB`<br><br>`\u2039`<br><br>`\u203A`<br><br>`\u003C`<br><br>`\u003E`<br><br> | | | Omit from links or buttons that open another page or move to the next or previous step in a process. Also known as angle brackets, angular quote brackets, or guillemets. |

-| Em dash | **—** | `&mdash;` | `\u2014` | <kbd>⌥ Option</kbd>+<kbd>⇧ Shift</kbd>+<kbd>-</kbd> | <kbd>Alt</kbd>+<kbd>0 1 5 1</kbd> | Avoid using dashes to separate text. If you must use dashes for this purpose — like this — use an em dash surrounded by spaces. |

-| En dash | **–** | `&ndash;` | `\u2013` | <kbd>⌥ Option</kbd>+<kbd>-</kbd> | <kbd>Alt</kbd>+<kbd>0 1 5 0</kbd> | Use an en dash without spaces instead of a hyphen to indicate a range of values, such as numbers, times, and dates: “3–5 kg”, “8:00 AM–12:30 PM”, “10–17 Jan” |

-| Hyphen | **-** | | | | | Use to represent negative numbers, or to avoid ambiguity in adjective-noun or noun-participle pairs. Example: “anti-inflammatory”; “5-mile walk.”<br><br>Omit in commonly understood terms and adverbs that end in *ly*: “frontend”, “greatly improved performance.”<br><br>Omit in the term “open source.” |

-| Parentheses | **( )** | | | | | Use only to define acronyms or jargon: “Secure web connections are based on a technology called SSL (the secure sockets layer).”<br><br>Avoid other uses and instead rewrite the text, or use dashes or commas to set off the information. If parentheses are required: If the parenthetical is a complete, independent sentence, place the period inside the parentheses; if not, the period goes outside. |

-

-When using the <kbd>Alt</kbd> keystrokes in Windows, use the numeric keypad, not the row of numbers above the alphabet, and be sure Num Lock is turned on.

-

----

-

-## Terminology

-Only use the terms below.

-

-When using verbs or adjectives:

-* If the context clearly refers to the object, use them alone. Example: `Edit` or `Closed`

-* If the context isn’t clear enough, use them with the object. Example: `Edit issue` or `Closed issues`

-

-### Search

-

-| Term | Use |

-| ---- | --- |

-| Search | When using all metadata to add criteria that match/don't match. Search can also affect ordering, by ranking best results. |

-| Filter | When taking a single criteria that removes items within a list that match/don't match. Filters do not affect ordering. |

-| Sort   | Orders a list based on a single or grouped criteria |

-

-### Projects and Groups

-

-| Term | Use | :no_entry_sign: Don't |

-| ---- | --- | ----- |

-| Members | When discussing the people who are a part of a project or a group. | Don't use `users`. |

-

-### Issues

-

-#### Adjectives (states)

-

-| Term | :no_entry_sign: Don’t |

-| ---- | --- |

-| Open | Don’t use `Pending` or `Created` |

-| Closed | Don’t use `Archived` |

-| Deleted | Don’t use `Removed` or `Trashed` |

-

-#### Verbs (actions)

-

-| Term | Use | :no_entry_sign: Don’t |

-| ---- | --- | --- |

-| New | Although it’s not a verb, `New` is a common standard and used for entering the creation mode of a non-existent issue | Don’t use `Create`, `Open`, or `Add` |

-| Create | Only to indicate when or who created an issue ||

-| Add | Associate an existing issue with an item or a list of items | Don’t use `New` or `Create` |

-| View | Open the detail page of an issue | Don’t use `Open` or `See` |

-| Edit | Enter the editing mode of an issue | Don’t use `Change`, `Modify` or `Update` |

-| Submit | Finalize the *creation* process of an issue | Don’t use `Add`, `Create`, `New`, `Open`, `Save` or `Save changes` |

-| Save | Finalize the *editing* process of an issue | Don’t use `Edit`, `Modify`, `Update`, `Submit`, or `Save changes` |

-| Cancel | Cancel the *creation* or *editing* process of an issue | Don’t use `Back`, `Close`, or `Discard` |

-| Close | Close an open issue | Don’t use `Archive` |

-| Re-open | Re-open a closed issue | Don’t use `Open` |

-| Delete | Permanently remove an issue from the system | Don’t use `Remove` |

-| Remove | Remove the association an issue with an item or a list of items | Don’t use `Delete` |

-

-### Merge requests

-

-#### Adjectives (states)

-

-| Term |

-| ---- |

-| Open |

-| Merged |

-

-#### Verbs (actions)

-

-| Term | Use | :no_entry_sign: Don’t |

-| ---- | --- | --- |

-| Add | Add a merge request | Do not use `create` or `new` |

-| View | View an open or merged merge request ||

-| Edit | Edit an open or merged merge request| Do not use `update` |

-| Approve | Approve an open merge request ||

-| Remove approval, unapproved | Remove approval of an open merge request | Do not use `unapprove` as that is not an English word|

-| Merge | Merge an open merge request ||

-

-### Comments & Discussions

-

-#### Comment

-A **comment** is a written piece of text that users of GitLab can create. Comments have the meta data of author and timestamp. Comments can be added in a variety of contexts, such as issues, merge requests, and discussions.

-

-#### Discussion

-A **discussion** is a group of 1 or more comments. A discussion can include subdiscussions. Some discussions have the special capability of being able to be **resolved**. Both the comments in the discussion and the discussion itself can be resolved.

-

-## Modals

-

-- Destruction buttons should be clear and always say what they are destroying.

-  E.g., `Delete page` instead of just `Delete`.

-- If the copy describes another action the user can take instead of the

-  destructive one, provide a way for them to do that as a secondary button.

-- Avoid the word `cancel` or `canceled` in the descriptive copy. It can be

-  confusing when you then see the `Cancel` button.

-

-see also: guidelines for [modal components](components.md#modals)

-

----

-

-Portions of this page are modifications based on work created and shared by the [Android Open Source Project][android project] and used according to terms described in the [Creative Commons 2.5 Attribution License][creative commons].

-

-[material design]: https://material.io/guidelines/

-[features]: https://about.gitlab.com/features/ "GitLab features page"

-[products]: https://about.gitlab.com/pricing/ "GitLab products page"

-[serial comma]: https://en.wikipedia.org/wiki/Serial_comma "“Serial comma” in Wikipedia"

-[android project]: http://source.android.com/

-[creative commons]: http://creativecommons.org/licenses/by/2.5/

+---
+redirect_to: 'https://design.gitlab.com/'
+---
+
+The content of this document was moved into the [GitLab Design System](https://design.gitlab.com/).
diff --git a/doc/development/ux_guide/features.md b/doc/development/ux_guide/features.md
index 9472995c68c..1e84bf608f4 100644
--- a/doc/development/ux_guide/features.md
+++ b/doc/development/ux_guide/features.md
@@ -1,57 +1,5 @@
-# Features
-
-## Contents
-* [Navigation](#navigation)
-* [Filtering](#filtering)
-* [Search results](#search-results)
-* [Conversations](#conversations)
-* [Empty states](#empty-states)
-
 ---
-
-## Navigation
-
-### Global navigation
-
-The global navigation is accessible via the menu button on the top left of the screen, and can be pinned to keep it open. It contains a consistent list of pages that allow you to view content that is across GitLab. For example, you can view your todos, issues and merge requests across projects and groups.
-
-![Global nav](img/features-globalnav.png)
-
-
-### Contextual navigation
-
-The navigation in the header is contextual to each page. These options change depending on if you are looking at a project, group, or settings page. There should be no more than 10 items on a level in the contextual navigation, allowing it to comfortably fit on a typical laptop screen. There can be up to too levels of navigation. Each sub nav group should be a self-contained group of functionality. For example, everything related to the issue tracker should be under the 'Issue' tab, while everything relating to the wiki will be grouped under the 'Wiki' tab. The names used for each section should be short and easy to remember, ideally 1-2 words in length.
-
-![Contextual nav](img/features-contextualnav.png)
-
-### Information architecture
-
-The [GitLab Product Map](https://gitlab.com/gitlab-org/gitlab-design/raw/master/production/resources/gitlab-map.png) shows a visual representation of the information architecture for GitLab.
-
+redirect_to: 'https://design.gitlab.com/'
 ---
 
-## Filtering
-
-Today, lists are filtered by a series of dropdowns. Some of these dropdowns allow multiselect (labels), while others allow you to filter to one option (milestones). However, we are currently implementing a [new model](https://gitlab.com/gitlab-org/gitlab-ce/issues/21747) for this, and will update the guide when it is ready.
-
-![Filters](img/features-filters.png)
-
----
-
-## Search results
-
-### Global search
-
-[Global search](https://gitlab.com/search?group_id=&project_id=13083&repository_ref=&scope=issues&search=mobile) allows you to search across items in a project, or even across multiple projects. You can switch tabs to filter on type of object, or filter by group.
-
-### List search
-
-There are several core lists in the GitLab experience, such as the Issue list and the Merge Request list. You are also able to [filter and search these lists](https://gitlab.com/gitlab-org/gitlab-ce/issues?utf8=%E2%9C%93&search=mobile). This UI will be updated with the [new filtering model](https://gitlab.com/gitlab-org/gitlab-ce/issues/21747).
-
----
-
-## Empty states
-
-Empty states need to be considered in the design of features. They are vital to helping onboard new users, making the experience feel more approachable and understandable. Empty states should feel inviting and provide just enough information to get people started. There should be a single call to action and a clear explanation of what to use the feature for.
-
-![Empty states](img/features-emptystates.png)
+The content of this document was moved into the [GitLab Design System](https://design.gitlab.com/).
diff --git a/doc/development/ux_guide/illustrations.md b/doc/development/ux_guide/illustrations.md
index 7e16c300921..ed072b6515f 100644
--- a/doc/development/ux_guide/illustrations.md
+++ b/doc/development/ux_guide/illustrations.md
@@ -1,86 +1,5 @@
-# Illustrations
-
-The illustrations should always align with topics and goals in specific context.
-
-## Principles
-
-#### Be simple.
-- For clarity, we use simple and specific elements to create our illustrations.
-
-#### Be optimistic.
-- We are an open-minded, optimistic, and friendly team. We should reflect those values in our illustrations to connect with our brand experience.
-
-#### Be gentle.
-- Our illustrations assist users in understanding context and guide users in the right direction. Illustrations are supportive, so they should be obvious but not aggressive.
-
-
-## Style
-
-#### Shapes
-- All illustrations are geometric rather than organic.
-- The illustrations are made by circles, rectangles, squares, and triangles.
-
-<img src="img/illustrations-geometric.png" width=224px alt="Example for geometric" />
-
-#### Stroke
-- Standard border thickness: **4px**
-- Depending on the situation, border thickness can be changed to **3px**. For example, when the illustration size is small, an illustration with 4px border thickness would look tight. In this case, the border thickness can be changed to 3px.
-- We use **rounded caps** and **rounded corner**.
-
-| Do | Don't |
-| -------- | -------- |
-| <img src="img/illustrations-caps-do.png" width= 133px alt="Do: caps and corner" /> | <img src="img/illustrations-caps-don't.png" width= 133px alt="Don't: caps and corner"/> |
-
-#### Radius
-- Standard corner radius: **10px**
-- Depending on the situation, corner radius can be changed to **5px**. For example, when the illustration size is small, an illustration with 10px corner radius would be over-rounded. In this case, the corner radius can be changed to 5px.
-
-<img src="img/illustrations-border-radius.png" width= 464px alt="Example for border radius"/>
-
-#### Size
-Depends on the situation, the illustration size can be the 3 types below:
-
-**Large**
-* Use case: Empty states, error pages(e.g. 404, 403)
-* For vertical layout, the illustration should not larger than **430*300 px**.
-* For horizontal layout, the illustration should not larger than **430*380 px**.
-
-| Vertical layout | Horizontal layout |
-| --------------- | ----------------- |
-| <img src="img/illustration-size-large-vertical.png" />  | <img src="img/illustration-size-large-horizontal.png" />
-
-**Medium**
-* Use case: Banner
-* The illustration should not larger than **240*160 px**
-* The illustration should keep simple and clear. We recommend not including too many elements in the medium size illustration.
-
-<img src="img/illustration-size-medium.png" width=983px />
-
-**Small**
-* Use case: Graphics for explanatory text, graphics for status.
-* The illustration should not larger than **160*90 px**.
-* The illustration should keep simple and clear. We recommend not including too many elements in the small size illustration.
-
-<img src="img/illustration-size-small.png" width=983px />
-
-**Illustration on mobile**
-- Keep the proportions in original ratio.
-
-#### Colors palette
-
-For consistency, we recommend choosing colors from our color palette.
-
-| Orange | Purple | Grey |
-| -------- | -------- | -------- |
-| <img src="img/illustrations-color-orange.png" width= 160px alt="Orange" /> | <img src="img/illustrations-color-purple.png" width= 160px alt="Purple" /> | <img src="img/illustrations-color-grey.png" width= 160px alt="Grey" /> |
-| #FC6D26   | #6B4FBB | #EEEEEE |
-
-#### Don't
-- Don't include the typography in the illustration.
-- Don't include tanuki in the illustration. If necessary, we recommend having tanuki monochromatic.
-
+---
+redirect_to: 'https://design.gitlab.com/foundations/illustration/'
 ---
 
-| Orange | Purple |
-| -------- | -------- |
-| <img src="img/illustrations-palette-oragne.png" width= 160px alt="Palette - Orange" /> | <img src="img/illustrations-palette-purple.png" width= 160px alt="Palette - Purple" /> |
+The content of this document was moved into the [GitLab Design System](https://design.gitlab.com/).
diff --git a/doc/development/ux_guide/index.md b/doc/development/ux_guide/index.md
index c59e7b72a1a..1e84bf608f4 100644
--- a/doc/development/ux_guide/index.md
+++ b/doc/development/ux_guide/index.md
@@ -1,70 +1,5 @@
-> We are in the process of transferring UX documentation to the [design.gitlab.com](https://gitlab.com/gitlab-org/design.gitlab.com) project. Any updates to these docs should be made in that project. If documentation does not yet exist within [design.gitlab.com](https://gitlab.com/gitlab-org/design.gitlab.com), [create an issue](https://gitlab.com/gitlab-org/design.gitlab.com/issues) and merge request to add your new changes.
-
-# GitLab UX Guide
-
-The goal of this guide is to provide standards, principles and in-depth information to design beautiful and effective GitLab features. This will be a living document, and we welcome contributions, feedback and suggestions.
-
-## Design
-
----
-
-### [Principles](principles.md)
-These guiding principles set a solid foundation for our design system, and should remain relatively stable over multiple releases. They should be referenced as new design patterns are created.
-
----
-
-### [Basics](basics.md)
-The basic ingredients of our experience establish our personality and feel. This section includes details about typography, iconography, and color.
-
 ---
-
-### [Animation](animation.md)
-Guidance on the timing, curving and motion for GitLab.
-
----
-
-### [Illustrations](illustrations.md)
-Guidelines for principals and styles related to illustrations for GitLab.
-
----
-
-### [Copy](copy.md)
-Conventions on text and messaging within labels, buttons, and other components.
-
----
-
-### [Components](components.md)
-Components are the controls that make up the GitLab experience, including guidance around buttons, links, dropdowns, etc.
-
----
-
-### [Surfaces](surfaces.md)
-The GitLab experience is broken apart into several surfaces. Each of these surfaces is designated for a specific scope or type of content. Examples include the header, global menu, side pane, etc.
-
----
-
-### [Features](features.md)
-The previous building blocks are combined into complete features in the GitLab UX. Examples include our navigation, filters, search results, and empty states.
-
----
-
-## Research
-
----
-
-### [Users](users.md)
-How we think about the variety of users of GitLab, from small to large teams, comparing opensource usage to enterprise, etc.
-
----
-
-## Other
-
----
-
-### [Tips for designers](tips.md)
-Tips for exporting assets, and other guidance.
-
+redirect_to: 'https://design.gitlab.com/'
 ---
 
-### [Resources](resources.md)
-Resources for GitLab UX
+The content of this document was moved into the [GitLab Design System](https://design.gitlab.com/).
diff --git a/doc/development/ux_guide/principles.md b/doc/development/ux_guide/principles.md
index 1a297cba2cc..1e84bf608f4 100644
--- a/doc/development/ux_guide/principles.md
+++ b/doc/development/ux_guide/principles.md
@@ -1,17 +1,5 @@
-# Principles
+---
+redirect_to: 'https://design.gitlab.com/'
+---
 
-These are the guiding principles that we should strive for to establish a solid foundation for the GitLab experience.
-
-## Professional and productive
-GitLab is a tool to support what people do, day in, day out. We need to respect the importance of their work, and avoid gimicky details.
-
-## Minimal and efficient
-While work can get complicated, GitLab is about bringing a sharp focus, helping our customers know what matters now.
-
-## Immediately recognizable
-When you look at any screen, you should know immediately that it is GitLab. Our personality is strong and consistent across product and marketing experiences.
-
-## Human and quirky
-We need to build empathy with our users, understanding their state of mind, and connect with them at a human level. Quirkiness is part of our DNA, and we should embrace it in the right moments and contexts.
-
-> TODO: Ensure these principles align well with the goals of the Marketing team
+The content of this document was moved into the [GitLab Design System](https://design.gitlab.com/).
diff --git a/doc/development/ux_guide/resources.md b/doc/development/ux_guide/resources.md
index db57258237f..baec235a8dd 100644
--- a/doc/development/ux_guide/resources.md
+++ b/doc/development/ux_guide/resources.md
@@ -1,17 +1,5 @@
-# Resources
+---
+redirect_to: 'https://design.gitlab.com/resources/design-resources'
+---
 
-## GitLab UI development kit
-
-We created a page inside GitLab where you can check commonly used html and css elements.
-
-When you run GitLab instance locally - just visit http://localhost:3000/help/ui page to see UI examples
-you can use during GitLab development.
-
-## Design repository
-
-All design files are stored in the [gitlab-design](https://gitlab.com/gitlab-org/gitlab-design)
-repository and maintained by GitLab UX designers.
-
-## [brand.ai](https://brand.ai/git-lab/primary-brand)
-
-We are in the process of capturing our UI paradigms on brand.ai, see https://brand.ai/git-lab/primary-brand
+The content of this document was moved into the [GitLab Design System](https://design.gitlab.com/).
diff --git a/doc/development/ux_guide/surfaces.md b/doc/development/ux_guide/surfaces.md
index 881d6aa4cd6..1e84bf608f4 100644
--- a/doc/development/ux_guide/surfaces.md
+++ b/doc/development/ux_guide/surfaces.md
@@ -1,47 +1,5 @@
-# Surfaces
-
-## Contents
-* [Header](#header)
-* [Global menu](#global-menu)
-* [Side pane](#side-pane)
-* [Content area](#content-area)
-
----
-
-![Surfaces UX](img/surfaces-ux.png)
-
-## Global menu
-
-This menu is to navigate to pages that contain content global to GitLab.
-
----
-
-## Header
-
-The header contains 3 main elements: Project switching and searching, user account avatar and settings, and a contextual menu that changes based on the current page.
-
-![Surfaces Header](img/surfaces-header.png)
-
 ---
-
-## Side pane
-
-The side pane holds supporting information and meta data for the information in the content area.
-
+redirect_to: 'https://design.gitlab.com/'
 ---
 
-## Content area
-
-The main content of the page. The content area can include other surfaces.
-
-### Item title bar
-
-The item title bar contains the top level information to identify the item, such as the name, id and status.
-
-![Item title](img/surfaces-contentitemtitle.png)
-
-### Item system information
-
-The system information block contains relevant system controlled information.
-
-![Item system information](img/surfaces-systeminformationblock.png)
+The content of this document was moved into the [GitLab Design System](https://design.gitlab.com/).
diff --git a/doc/development/ux_guide/tips.md b/doc/development/ux_guide/tips.md
index 8348de4f8a2..1e84bf608f4 100644
--- a/doc/development/ux_guide/tips.md
+++ b/doc/development/ux_guide/tips.md
@@ -1,44 +1,5 @@
-# Tips
-
-## Contents
-* [SVGs](#svgs)
-
+---
+redirect_to: 'https://design.gitlab.com/'
 ---
 
-## SVGs
-
-When exporting SVGs, be sure to follow the following guidelines:
-
-1. Convert all strokes to outlines.
-2. Use pathfinder tools to combine overlapping paths and create compound paths.
-3. SVGs that are limited to one color should be exported without a fill color so the color can be set using CSS.
-4. Ensure that exported SVGs have been run through an [SVG cleaner](https://github.com/RazrFalcon/SVGCleaner) to remove unused elements and attributes.
-
-You can open your svg in a text editor to ensure that it is clean.
-Incorrect files will look like this:
-
-```xml
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<svg width="16px" height="17px" viewBox="0 0 16 17" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
-    <!-- Generator: Sketch 3.7.2 (28276) - http://www.bohemiancoding.com/sketch -->
-    <title>Group</title>
-    <desc>Created with Sketch.</desc>
-    <defs></defs>
-    <g id="Page-1" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
-        <g id="Group" fill="#7E7C7C">
-            <path d="M15.1111,1 L0.8891,1 C0.3981,1 0.0001,1.446 0.0001,1.996 L0.0001,15.945 C0.0001,16.495 0.3981,16.941 0.8891,16.941 L15.1111,16.941 C15.6021,16.941 16.0001,16.495 16.0001,15.945 L16.0001,1.996 C16.0001,1.446 15.6021,1 15.1111,1 L15.1111,1 L15.1111,1 Z M14.0001,6.0002 L14.0001,14.949 L2.0001,14.949 L2.0001,6.0002 L14.0001,6.0002 Z M14.0001,4.0002 L14.0001,2.993 L2.0001,2.993 L2.0001,4.0002 L14.0001,4.0002 Z" id="Combined-Shape"></path>
-            <polygon id="Fill-11" points="3 2.0002 5 2.0002 5 0.0002 3 0.0002"></polygon>
-            <polygon id="Fill-16" points="11 2.0002 13 2.0002 13 0.0002 11 0.0002"></polygon>
-            <path d="M5.37709616,11.5511984 L6.92309616,12.7821984 C7.35112915,13.123019 7.97359761,13.0565604 8.32002627,12.6330535 L10.7740263,9.63305349 C11.1237073,9.20557058 11.0606364,8.57555475 10.6331535,8.22587373 C10.2056706,7.87619272 9.57565475,7.93926361 9.22597373,8.36674651 L6.77197373,11.3667465 L8.16890384,11.2176016 L6.62290384,9.98660159 C6.19085236,9.6425813 5.56172188,9.71394467 5.21770159,10.1459962 C4.8736813,10.5780476 4.94504467,11.2071781 5.37709616,11.5511984 L5.37709616,11.5511984 Z" id="Stroke-21"></path>
-        </g>
-    </g>
-</svg>
-```
-
-Correct file will look like this:
-
-```xml
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 17" enable-background="new 0 0 16 17"><path d="m15.1 1h-2.1v-1h-2v1h-6v-1h-2v1h-2.1c-.5 0-.9.5-.9 1v14c0 .6.4 1 .9 1h14.2c.5 0 .9-.4.9-1v-14c0-.5-.4-1-.9-1m-1.1 14h-12v-9h12v9m0-11h-12v-1h12v1"/><path d="m5.4 11.6l1.5 1.2c.4.3 1.1.3 1.4-.1l2.5-3c.3-.4.3-1.1-.1-1.4-.5-.4-1.1-.3-1.5.1l-1.8 2.2-.8-.6c-.4-.3-1.1-.3-1.4.2-.3.4-.3 1 .2 1.4"/></svg>
-```
-
-> TODO: Checkout [https://github.com/svg/svgo](https://github.com/svg/svgo)
+The content of this document was moved into the [GitLab Design System](https://design.gitlab.com/).
diff --git a/doc/development/ux_guide/users.md b/doc/development/ux_guide/users.md
index 6afb33cfc36..11bac11257c 100644
--- a/doc/development/ux_guide/users.md
+++ b/doc/development/ux_guide/users.md
@@ -1,310 +1,5 @@
-# UX Personas
-
-* [Nazim Ramesh](#nazim-ramesh)
-    - Small to medium size organizations using GitLab CE
-* [Matthieu Poirier](#matthieu-poirier)
-    - Responsible for managing and maintaining GitLab installation
-    - Any size organization
-    - Using CE or EE
-* [James Mackey](#james-mackey)
-    - Medium to large size organizations using CE or EE
-    - Small organizations using EE
-* [Karolina Plaskaty](#karolina-plaskaty)
-    - Using GitLab.com for personal/hobby projects
-    - Would like to use GitLab at work
-    - Working within a medium to large size organization
-
----
-
-## Nazim Ramesh
-- Small to medium size organizations using GitLab CE
-
-![nazim-ramesh](img/nazim-ramesh.png)
-
-### Demographics
-
-**Age**
-
-32 years old
-
-**Location**
-
-Germany
-
-**Education**
-
-Bachelor of Science in Computer Science
-
-**Occupation**
-
-Full-stack web developer
-
-**Programming experience**
-
-Over 10 years
-
-**Frequently used programming languages**
-
-JavaScript, SQL, PHP
-
-**Hobbies / interests**
-
-Functional programming, open source, gaming, web development, and web security.
-
-### Motivations
-Nazim works for a software development company which currently hires around 80 people. When Nazim first joined the company, the engineering team were using Subversion (SVN) as their primary form of source control. However, Nazim felt SVN was not flexible enough to work with many feature branches and noticed that developers with less experience of source control struggled with the central-repository nature of SVN. Armed with a wish list of features, Nazim began comparing source control tools. A search for "self-hosted Git server repository management" returned GitLab. In his own words, Nazim explains why he wanted the engineering team to start using GitLab:
-
->"I wanted them to switch away from SVN. I needed a server application to manage repositories. The common tools that were around just didn't meet the requirements. Most of them were too simple or plain...GitLab provided all the required features. Also, costs had to be low since we don't have a big budget for those things...the Community Edition was perfect in this regard."
-
-In his role as a full-stack web developer, Nazim could recommend products that he would like the engineering team to use, but final approval lay with his line manager, Mike, VP of Engineering. Nazim recalls that he was met with reluctance from his colleagues when he raised moving to Git and using GitLab.
-
->"The biggest challenge...why should we change anything at all from the status quo? We needed to switch from SVN to Git. They knew they needed to learn Git and a Git workflow...using Git was scary to my colleagues...they thought it was more complex than SVN to use."
-
-Undeterred, Nazim decided to migrate a couple of projects across to GitLab.
-
->"Old SVN users couldn't see the benefits of Git at first. It took a month or two to convince them."
-
-Slowly, by showing his colleagues how easy it was to use Git, the majority of the team's projects were migrated to GitLab.
-
-The engineering team have been using GitLab CE for around 2 years now. Nazim credits himself as being entirely responsible for his company's decision to move to GitLab.
-
-### Frustrations
-#### Adoption to GitLab has been slow
-Not only has the engineering team had to get to grips with Git, they've also had to adapt to using GitLab. Due to lack of training and existing skills in other tools, the full feature set of GitLab CE is not being utilized. Nazim sold GitLab to his manager as an ‘all in one' tool which would replace multiple tools used within the company, thus saving costs. Nazim hasn't had the time to integrate the legacy tools to GitLab and he's struggling to convince his peers to change their habits.
-
-#### Missing Features
-Nazim's company want GitLab to be able to do everything. There isn't a large budget for software, so they're selective about what tools are implemented. It needs to add real value to the company. In order for GitLab to be widely adopted and to meet the requirements of different roles within the company, it needs a host of features. When an individual within Nazim's company wants to know if GitLab has a specific feature or does a particular thing, Nazim is the person to ask. He becomes the point of contact to investigate, build or sometimes just raise the feature request. Nazim gets frustrated when GitLab isn't able to do what he or his colleagues need it to do.
-
-#### Regressions and bugs
-Nazim often has to calm down his colleagues, when a release contains regressions or new bugs. As he puts it "every new version adds something awesome, but breaks something". He feels that "old issues for minor annoyances get quickly buried in the mass of open issues and linger for a very long time. More generally, I have the feeling that GitLab focus on adding new functionalities, but overlook a bunch of annoying minor regressions or introduced bugs." Due to limited resource and expertise within the team, not only is it difficult to remain up-to-date with the frequent release cycle, it's also counterproductive to fix workflows every month.
-
-#### Uses too much RAM and CPU
->"Memory usages mean that if we host it from a cloud-based host like AWS, we spend almost as much on the instance as what we would pay GitHub"
-
-
-#### UI/UX
-GitLab's interface initially attracted Nazim when he was comparing version control software. He thought it would help his less technical colleagues to adapt to using Git and perhaps, GitLab could be rolled out to other areas of the business, beyond engineering. However, using GitLab's interface daily has left him frustrated at the lack of personalization/control over his user experience. He's also regularly lost in a maze of navigation. Whilst he acknowledges that GitLab listens to its users and that the interface is improving, he becomes annoyed when the changes are too progressive. "Too frequent UI changes. Most of them tend to turn out great after a few cycles of fixes, but the frequency is still far too high for me to feel comfortable to always stay on the current release."
-
-### Goals
-* To convince his colleagues to fully adopt GitLab CE, thus improving workflow and collaboration.
-* To use a feature-rich version control platform that covers all stages of the development lifecycle, in order to reduce dependencies on other tools.
-* To use an intuitive and stable product, so he can spend more time on his core job responsibilities and less time bug-fixing, guiding colleagues, etc.
-
----
-## Matthieu Poirier
-- Responsible for managing and maintaining GitLab installation
-- Any size organization
-- Using CE or EE
-
-![matthieu-poirier](img/matthieu-poirier.png)
-
-### Demographics
-
-**Age**
- 
-42 years old
-
-**Location**
-
-France
-
-**Education**
-
-Masters Degree in Computer Science
-
-**Occupation**
-
-DevOps Engineer
-
-**Programming experience**
-
-Over 10 years
-
-**Frequently used programming languages**
-
-JavaScript, SQL, PHP and Node.js
-
-**Hobbies / interests**
-
-Functional programming, data analysis, building apps, and tools.
-
-### Motivations
-Matthieu works in DevOps for a web services company which currently hires 90 staff. When Matthieu first joined the company, he was responsible for managing a custom built in-house bug tracking tool and release management system. Over time, as the company grew, his colleagues requested more features and tools to help them in their day-to-day work. To meet their needs, Matthieu was forced to "hack together" a solution. In his own words, Matthieu explains that it became:
-
->"...a huge pain managing access to all the individual pieces. In addition, they didn't have any integration with each other, nobody ended up using them and we couldn't do any workflows with merge requests and the like. I was sick of managing all those separate parts and wanted to move to a single platform that would handle it all."
-
-
-He further explains that he wanted to introduce "better, easier, more formal code reviews" and to start using continuous integration and deployment.
-
-Matthieu tried to find a platform which would consolidate the company's existing toolset, and centralize code, documentation, and issues. He discovered GitHub, but the price was an issue:
-
->"We needed to host our code on-site and wanted GitHub Enterprise functionality without the GitHub Enterprise costs."
-
-
-Not only was GitLab cheaper than GitHub, it was also more cost-effective than maintaining multiple tools. Subsequently, Matthieu found it easy to sell the merits of GitLab to his manager.
-
-Matthieu describes GitLab as:
-
->"the only tool that offers the real feeling of having everything you need in one place."
-
-
-He credits himself as being entirely responsible for moving his company to GitLab. 
-
-### Frustrations
-#### Updating to the latest release
-Matthieu introduced his company to GitLab. He is responsible for maintaining and managing the company's installation in addition to his day job. He feels updates are too frequent and he doesn't always have sufficient time to update GitLab. As a result, he's not up to date with releases. 
-
-Matthieu tried to set up automatic updates, however, as he isn't a Systems Administrator, he wasn't confident in his set-up. He feels he should be able to "upgrade without users even noticing" but hasn't figured out how to do this yet. Matthieu would like the "update process to be triggered from the Admin Panel, perhaps accompanied with a changelog and the option to skip updates."
-
-Matthieu is looking for confirmation that his update procedure is "secure and efficient" so more tutorials related to this topic would be useful to him.
-
-#### Configuration
-Matthieu dislikes using the combination of gitlab.rb and the UI for changing settings. He explains that it "would be nice to be able to configure more from the Admin UI rather than just the config files."
-
-#### Creating a backup
-Matthieu explains that the "backup solution is not well integrated into the UI", for example, he "cannot see if backups succeeded" or whether they have been rolled back to via the UI.
-
-#### Onboarding
-It's Matthieu's responsibility to get teams across his organization up and running with GitLab. He explains that whilst many teams might be leveraging GitLab, they are:
-
->"..not aware of GitLab's powerful CI or our omnibus install of Mattermost...It would be nice to have a tutorial type walkthrough available when a new user logs in on how to get started with all these features. AutoDevOps may solve some of this, but GitLab has many powerful features wrapped up into it and some [teams] may just think that it is only a Git repo similar to GitHub."
-
-
-He states that there has been: "a sluggishness of others to adapt" and it's "a low-effort adaptation at that."
-
-### Goals
-* To save time. One of the reasons Matthieu moved his company to GitLab was to reduce the effort it took him to manage and configure multiple tools, thus saving him time. He has to balance his day job in addition to managing the company's GitLab installation and onboarding new teams to GitLab. 
-* To use a platform which is easy to manage. Matthieu isn't a Systems Administrator, and when updating GitLab, creating backups, etc. He would prefer to work within GitLab's UI. Explanations / guided instructions when configuring settings in GitLab's interface would really help Matthieu. He needs reassurance that what he is about to change is 
-
-1. the right setting
-2. will provide him with the desired result he wants.
-
-* Matthieu needs to educate his colleagues about GitLab. Matthieu's colleagues won't adopt GitLab as they're unaware of its capabilities and the positive impact it could have on their work. Matthieu needs support in getting this message across to them.
-
 ---
-
-## James Mackey
-- Medium to large size organizations using CE or EE
-- Small organizations using EE
-
-![james-mackey.png](img/james-mackey.png)
-
-### Demographics
-
-**Age**
-
-36 years old
-
-**Location**
-
-US
-
-**Education**
-
-Masters degree in Computer Science
-
-**Occupation**
-
-Full-stack web developer
-
-**Programming experience**
-
-Over 10 years
-
-**Frequently used programming languages**
-
-JavaScript, SQL, Node.js, Java, PHP, Python
-
-**Hobbies / interests**
-
-DevOps, open source, web development, science, automation, and electronics.
-
-### Motivations
-James works for a research company which currently hires around 800 staff. He began using GitLab.com back in 2013 for his own open source, hobby projects and loved "the simplicity of installation, administration and use". After using GitLab for over a year, he began to wonder about using it at work. James explains:
-
->"We first installed the CE edition...on a staging server for a PoC and asked a beta team to use it, specifically for the Merge Request features. Soon other teams began asking us to be beta users too because the team that was already using GitLab was really enjoying it."
-
-
-James and his colleagues also reviewed competitor products including GitHub Enterprise, but they found it "less innovative and with considerable costs...GitLab had the features we wanted at a much lower cost per head than GitHub".
-
-The company James works for provides employees with a discretionary budget to spend how they want on software, so James and his team decided to upgrade to EE.
-
-James feels partially responsible for his organization's decision to start using GitLab.
-
->"It's still up to the teams themselves [to decide] which tools to use. We just had a great experience moving our daily development to GitLab, so other teams have followed the path or are thinking about switching."
-
-
-### Frustrations
-#### Third Party Integration
-Some of GitLab EE's features are too basic, in particular, issues boards which do not have the level of reporting that James and his team need. Subsequently, they still need to use GitLab EE in conjunction with other tools, such as JIRA. Whilst James feels it isn't essential for GitLab to meet all his needs (his company are happy for him to use, and pay for, multiple tools), he sometimes isn't sure what is/isn't possible with plugins and what level of custom development he and his team will need to do.
-
-#### UX/UI
-James and his team use CI quite heavily for several projects. Whilst they've welcomed improvements to the builds and pipelines interface, they still have some difficulty following build process on the different tabs under Pipelines. Some confusion has arisen from not knowing where to find different pieces of information or how to get to the next stages logs from the current stage's log output screen. They feel more intuitive linking and flow may alleviate the problem. Generally, they feel GitLab's navigation needs to reviewed and optimized.
-
-#### Permissions
->"There is no granular control over user or group permissions. The permissions for a project are too tightly coupled to the permissions for Gitlab CI/build pipelines."
-
-
-### Goals
-* To be able to integrate third-party tools easily with GitLab EE and to create custom integrations and patches where needed.
-* To use GitLab EE primarily for code hosting, merge requests, continuous integration and issue management. James and his team want to be able to understand and use these particular features easily.
-* To able to share one instance of GitLab EE with multiple teams across the business. Advanced user management, the ability to separate permissions on different parts of the source code, etc are important to James.
-
+redirect_to: 'https://design.gitlab.com/getting-started/personas/'
 ---
 
-## Karolina Plaskaty
-- Using GitLab.com for personal/hobby projects
-- Would like to use GitLab at work
-- Working within a medium to large size organization
-
-![karolina-plaskaty.png](img/karolina-plaskaty.png)
-
-### Demographics
-
-**Age**
-
-26 years old
-
-**Location**
-
-UK
-
-**Education**
-
-Self taught
-
-**Occupation**
-
-Junior web-developer
-
-**Programming experience**
-
-6 years
-
-**Frequently used programming languages**
-
-JavaScript and SQL
-
-**Hobbies / interests**
-
-Web development, mobile development, UX, open source, gaming, and travel.
-
-### Motivations
-Karolina has been using GitLab.com for around a year. She roughly spends 8 hours every week programming, of that, 2 hours is spent contributing to open source projects. Karolina contributes to open source projects to gain programming experience and to give back to the community. She likes GitLab.com for its free private repositories and range of features which provide her with everything she needs for her personal projects. Karolina is also a massive fan of GitLab's values and the fact that it isn't a "behemoth of a company".  She explains that "displaying every single thing (doc, culture, assumptions, development...) in the open gives me greater confidence to choose Gitlab personally and to recommend it at work."  She's also an avid reader of GitLab's blog.
-
-Karolina works for a software development company which currently hires around 500 people. Karolina would love to use GitLab at work but the company has used GitHub Enterprise for a number of years. She describes management at her company as "old fashioned" and explains that it's "less of a technical issue and more of a cultural issue" to convince upper management to move to GitLab. Karolina is also relatively new to the company so she's apprehensive about pushing too hard to change version control platforms.
-
-### Frustrations
-#### Unable to use GitLab at work
-Karolina wants to use GitLab at work but isn't sure how to approach the subject with management. In her current role, she doesn't feel that she has the authority to request GitLab.
-
-#### Performance
-GitLab.com is frequently slow and unavailable. Karolina has also heard that GitLab is a "memory hog"  which has deterred her from running GitLab on her own machine for just hobby / personal projects.
-
-#### UX/UI
-Karolina has an interest in UX and therefore has strong opinions about how GitLab should look and feel. She feels the interface is cluttered, "it has too many links/buttons" and the navigation "feels a bit weird sometimes. I get lost if I don't pay attention." As Karolina also enjoys contributing to open-source projects, it's important to her that GitLab is well designed for public repositories, she doesn't feel that GitLab currently achieves this.
-
-### Goals
-* To develop her programming experience and to learn from other developers.
-* To contribute to both her own and other open source projects.
-* To use a fast and intuitive version control platform.
\ No newline at end of file
+The content of this document was moved into the [GitLab Design System](https://design.gitlab.com/).
diff --git a/doc/development/what_requires_downtime.md b/doc/development/what_requires_downtime.md
index b668c9de6a0..3630a28fae9 100644
--- a/doc/development/what_requires_downtime.md
+++ b/doc/development/what_requires_downtime.md
@@ -300,7 +300,7 @@ 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
+1. 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.