5 files changed, 73 insertions, 2 deletions
diff --git a/doc/development/code_review.md b/doc/development/code_review.md
index 4ed89146072..e3f37616757 100644
--- a/doc/development/code_review.md
+++ b/doc/development/code_review.md
@@ -133,6 +133,55 @@ reviewee.
   tomorrow. When you are not able to find the right balance, ask other people
   about their opinion.
 
+### GitLab-specific concerns
+
+GitLab is used in a lot of places. Many users use
+our [Omnibus packages](https://about.gitlab.com/installation/), but some use
+the [Docker images](https://docs.gitlab.com/omnibus/docker/), some are
+[installed from source](https://docs.gitlab.com/ce/install/installation.html),
+and there are other installation methods available. GitLab.com itself is a large
+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
+     these.
+2. **Database migrations** must be:
+  1. Reversible.
+  2. 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:
+     - 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**
+   [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,
+     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
+     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
+     (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
+   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
+   [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
+     [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
+   [shared files](shared_files.md) when an alternative solution is available.
+
 ### Credits
 
 Largely based on the [thoughtbot code review guide].
diff --git a/doc/development/doc_styleguide.md b/doc/development/doc_styleguide.md
index 36c55cbaceb..90d1d9657b9 100644
--- a/doc/development/doc_styleguide.md
+++ b/doc/development/doc_styleguide.md
@@ -105,8 +105,8 @@ merge request.
   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. It is advised to mention one or all
-  of the following GitLab members for a review: `@axil`, `@rspeicher`, `@marcia`,
-  `@SeanPackham`. This is to ensure that no document with wrong heading is going
+  of the following GitLab members for a review: `@axil`, `@rspeicher`, `@marcia`.
+  This is to ensure that no document with wrong heading is going
   live without an audit, thus preventing dead links and redirection issues when
   corrected
 - Leave exactly one newline after a heading
diff --git a/doc/development/fe_guide/performance.md b/doc/development/fe_guide/performance.md
index 2ddcbe13afa..14ac1133cc0 100644
--- a/doc/development/fe_guide/performance.md
+++ b/doc/development/fe_guide/performance.md
@@ -23,6 +23,19 @@ controlled by the server.
 1. The backend code will most likely be using etags. You do not and should not check for status
 `304 Not Modified`. The browser will transform it for you.
 
+### Lazy Loading
+
+To improve the time to first render we are using lazy loading for images. This works by setting 
+the actual image source on the `data-src` attribute. After the HTML is rendered and JavaScript is loaded, 
+the value of `data-src` will be moved to `src` automatically if the image is in the current viewport.
+
+*  Prepare images in HTML for lazy loading by renaming the `src` attribute to `data-src` AND adding the class `lazy`
+*  If you are using the Rails `image_tag` helper, all images will be lazy-loaded by default unless `lazy: false` is provided.
+
+If you are asynchronously adding content which contains lazy images then you need to call the function
+`gl.lazyLoader.searchLazyImages()` which will search for lazy images and load them if needed. 
+But in general it should be handled automatically through a `MutationObserver` in the lazy loading function.
+
 ## Reducing Asset Footprint
 
 ### Page-specific JavaScript
diff --git a/doc/development/fe_guide/style_guide_js.md b/doc/development/fe_guide/style_guide_js.md
index ae844fa1051..149a0159680 100644
--- a/doc/development/fe_guide/style_guide_js.md
+++ b/doc/development/fe_guide/style_guide_js.md
@@ -447,6 +447,7 @@ A forEach will cause side effects, it will be mutating the array being iterated.
   1. `name`
   1. `props`
   1. `mixins`
+  1. `directives`
   1. `data`
   1. `components`
   1. `computedProps`
diff --git a/doc/development/ux_guide/copy.md b/doc/development/ux_guide/copy.md
index 794c8eb6bfe..12e8d0a31bb 100644
--- a/doc/development/ux_guide/copy.md
+++ b/doc/development/ux_guide/copy.md
@@ -106,6 +106,14 @@ 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 |