Merge remote-tracking branch 'upstream/master' into no-ivar-in-modules

* upstream/master: (168 commits)
  Update CHANGELOG.md for 10.0.1
  Remove Grit settings from default settings
  Fix duplicate key errors in PostDeployMigrateUserExternalMailData migration
  Workaround for #38259
  Workaround for n+1 in Projects::TreeController#show
  Removed old icons from project page
  Make branches page translatable
  fix typo in icons section
  Don't show it if there's no project.
  Update CHANGELOG.md for 10.0.0
  Inform user that current shared projects will remain shared
  Allow the git circuit breaker to correctly handle missing repository storages
  Reserve refs/replace cos `git-replace` is using it
  Resolve "Better SVG Usage in the Frontend"
  Replace the 'project/service.feature' spinach test with an rspec analog
  Replace the 'project/shortcuts.feature' spinach test with an rspec analog
  Removed two legacy config options
  Fix rendering double note issue.
  IssueNotes: Switch back to Write pane when note cancel or submit.
  Upgrade Nokogiri because of CVE-2017-9050
  ...

7 files changed, 136 insertions, 20 deletions

diff --git a/doc/development/code_review.md b/doc/development/code_review.md
index 64a89976300..7165b8062a7 100644
--- a/doc/development/code_review.md
+++ b/doc/development/code_review.md
@@ -9,8 +9,18 @@ There are a few rules to get your merge request accepted:
     **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]**.
+  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 [Build team member][team]**. See [how to work with the Build team][build handbook] for more details.
 1. To lower the amount of merge requests maintainers need to review, you can
diff --git a/doc/development/fe_guide/icons.md b/doc/development/fe_guide/icons.md
new file mode 100644
index 00000000000..a76e978bd26
--- /dev/null
+++ b/doc/development/fe_guide/icons.md
@@ -0,0 +1,40 @@
+# Icons
+
+We are using SVG Icons in GitLab with a SVG Sprite, due to this the icons are only loaded once and then referenced through an ID. The sprite SVG is located under `/assets/icons.svg`. Our goal is to replace one by one all inline SVG Icons (as those currently bloat the HTML) and also all Font Awesome usages.
+
+### Usage in HAML/Rails
+
+To use a sprite Icon in HAML or Rails we use a specific helper function : 
+
+`sprite_icon(icon_name, size: nil, css_class: '')`
+
+**icon_name** Use the icon_name that you can find in the SVG Sprite (Overview is available under `/assets/sprite.symbol.html`).
+**size (optional)** Use one of the following sizes : 16,24,32,48,72 (this will be translated into a `s16` class)
+**css_class (optional)** If you want to add additional css classes
+
+**Example** 
+
+`= sprite_icon('issues', size: 72, css_class: 'icon-danger')`
+
+**Output from example above**
+
+`<svg class="s72 icon-danger"><use xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="/assets/icons.svg#issues"></use></svg>`
+
+### Usage in HTML/JS
+
+Please use the following function inside JS to render an icon : 
+`gl.utils.spriteIcon(iconName)`
+
+## Adding a new icon to the sprite
+
+All Icons and Illustrations are managed in the [gitlab-svgs](https://gitlab.com/gitlab-org/gitlab-svgs) repository which is added as a dev-dependency.
+
+To upgrade to a new SVG Sprite version run `yarn upgrade https://gitlab.com/gitlab-org/gitlab-svgs` and then run `yarn run svg`. This task will copy the svg sprite and all illustrations in the correct folders.
+
+# SVG Illustrations
+
+Please use from now on for any SVG based illustrations simple `img` tags to show an illustration by simply using either `image_tag` or `image_path` helpers. Please use the class `svg-content` around it to ensure nice rendering. The illustrations are also organised in the [gitlab-svgs](https://gitlab.com/gitlab-org/gitlab-svgs) repository (as they are then automatically optimised).
+
+**Example**
+
+`= image_tag 'illustrations/merge_requests.svg'`
diff --git a/doc/development/fe_guide/index.md b/doc/development/fe_guide/index.md
index 64bcb4a0257..d84801f91d4 100644
--- a/doc/development/fe_guide/index.md
+++ b/doc/development/fe_guide/index.md
@@ -98,6 +98,11 @@ Vue specific design patterns and practices.
 
 ---
 
+## [Icons](icons.md)
+How we use SVG for our Icons.
+
+---
+
 ## Style Guides
 
 ### [JavaScript Style Guide](style_guide_js.md)
diff --git a/doc/development/img/manual_build_docs.png b/doc/development/img/manual_build_docs.png
index fef767c2a79..615facabb5f 100644
--- a/doc/development/img/manual_build_docs.png
+++ b/doc/development/img/manual_build_docs.png
diff --git a/doc/development/ux_guide/basics.md b/doc/development/ux_guide/basics.md
index a436e9b1948..e215026bcca 100644
--- a/doc/development/ux_guide/basics.md
+++ b/doc/development/ux_guide/basics.md
@@ -32,19 +32,17 @@ This is the typeface used for code blocks and references to commits, branches, a
 ---
 
 ## Icons
-GitLab uses Font Awesome icons throughout our interface.
 
-| | |
-| :-----------: | :---- |
-| ![Trash icon](img/icon-trash.png) | The trash icon is used for destructive actions that deletes information. |
-| ![Edit icon](img/icon-edit.png) | The pencil icon is used for editing content such as comments.|
-| ![Notification icon](img/icon-notification.png) | The bell icon is for notifications, such as Todos. |
-| ![Subscribe icon](img/icon-subscribe.png) | The eye icon is for subscribing to updates. For example, you can subscribe to a label and get updated on issues with that label. |
-| ![RSS icon](img/icon-rss.png) | The standard RSS icon is used for linking to RSS/atom feeds. |
-| ![Close icon](img/icon-close.png) | An 'x' is used for closing UI elements such as dropdowns. |
-| ![Add icon](img/icon-add.png) | A plus is used when creating new objects, such as issues, projects, etc. |
-
-> TODO: update this section, add more general guidance to icon usage and personality, etc.
+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.
 
 ---
 
diff --git a/doc/development/ux_guide/img/icon-spec.png b/doc/development/ux_guide/img/icon-spec.png
new file mode 100644
index 00000000000..56b19610dc1
--- /dev/null
+++ b/doc/development/ux_guide/img/icon-spec.png
diff --git a/doc/development/writing_documentation.md b/doc/development/writing_documentation.md
index 479258f743e..b1eb020a592 100644
--- a/doc/development/writing_documentation.md
+++ b/doc/development/writing_documentation.md
@@ -106,21 +106,84 @@ CE and EE.
 
 ## Previewing the changes live
 
-If you want to preview your changes live, you can use the manual `build-docs`
-job in your merge request.
+If you want to preview the doc changes of your merge request live, you can use
+the manual `review-docs-deploy` job in your merge request.
+
+TIP: **Tip:**
+If your branch contains only documentation changes, you can use
+[special branch names](#testing) to avoid long running pipelines.
 
 ![Manual trigger a docs build](img/manual_build_docs.png)
 
 This job will:
 
 1. Create a new branch in the [gitlab-docs](https://gitlab.com/gitlab-com/gitlab-docs)
-   project named after the scheme: `<CE/EE-branch-slug>-built-from-ce-ee`
-1. Trigger a pipeline and build the docs site with your changes
-
-Look for the docs URL at the output of the `build-docs` job.
-
->**Note:**
+   project named after the scheme: `preview-<branch-slug>`
+1. Trigger a cross project pipeline and build the docs site with your changes
+
+After a few minutes, the Review App will be deployed and you will be able to
+preview the changes. The docs URL can be found in two places:
+
+- In the merge request widget
+- In the output of the `review-docs-deploy` job, which also includes the
+  triggered pipeline so that you can investigate whether something went wrong
+
+In case the Review App URL returns 404, follow these steps to debug:
+
+1. **Did you follow the URL from the merge request widget?** If yes, then check if
+   the link is the same as the one in the job output. It can happen that if the
+   branch name slug is longer than 35 characters, it is automatically
+   truncated. That means that the merge request widget will not show the proper
+   URL due to a limitation of how `environment: url` works, but you can find the
+   real URL from the output of the `review-docs-deploy` job.
+1. **Did you follow the URL from the job output?** If yes, then it means that
+   either the site is not yet deployed or something went wrong with the remote
+   pipeline. Give it a few minutes and it should appear online, otherwise you
+   can check the status of the remote pipeline from the link in the job output.
+   If the pipeline failed or got stuck, drop a line in the `#docs` chat channel.
+
+TIP: **Tip:**
+Someone that has no merge rights to the CE/EE projects (think of forks from
+contributors) will not be able to run the manual job. In that case, you can
+ask someone from the GitLab team who has the permissions to do that for you.
+
+NOTE: **Note:**
 Make sure that you always delete the branch of the merge request you were
 working on. If you don't, the remote docs branch won't be removed either,
 and the server where the Review Apps are hosted will eventually be out of
 disk space.
+
+### Behind the scenes
+
+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 [`scirpts/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)