Merge remote-tracking branch 'upstream/master' into 42572-release-controller

* upstream/master: (889 commits)
  SlackService - respect `notify_only_default_branch` for push events
  Clarify usage ping wording in admin area
  Update incoming emails documents
  Allow to include also descendant group labels
  Update docs on grouping CI jobs
  Support additional LabelsFinder parameters for group labels
  Extend Cluster Applications to install GitLab Runner to Kubernetes cluster
  Remove registry list webpack entry point
  Remove trailing newline that was causing an EE conflict
  Small fixes in Vuex docs
  Remove u2f webpack bundle
  Update documentation WRT to request parameters
  remove common_vue CommonsChunk config
  Fetch commit signatures from Gitaly in batches
  migrate stl_viewer to dynamic import
  migrate sketch_viewer to dynamic import
  migrate pdf_viewer to dynamic import
  migrate notebook_viewer to dynamic import
  migrate balsamiq_viewer to dynamic import
  Add some strings that were missing in gitlab.pot
  ...

1 files changed, 12 insertions, 0 deletions

diff --git a/doc/development/fe_guide/performance.md b/doc/development/fe_guide/performance.md
index 14ac1133cc0..98e43931a02 100644
--- a/doc/development/fe_guide/performance.md
+++ b/doc/development/fe_guide/performance.md
@@ -36,6 +36,15 @@ If you are asynchronously adding content which contains lazy images then you nee
 `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.
 
+### Animations
+
+Only animate `opacity` & `transform` properties. Other properties (such as `top`, `left`, `margin`, and `padding`) all cause
+Layout to be recalculated, which is much more expensive. For details on this, see "Styles that Affect Layout" in
+[High Performance Animations][high-perf-animations].
+
+If you _do_ need to change layout (e.g. a sidebar that pushes main content over), prefer [FLIP][flip] to change expensive
+properties once, and handle the actual animation with transforms.
+
 ## Reducing Asset Footprint
 
 ### Page-specific JavaScript
@@ -87,6 +96,7 @@ General tips:
 - Compress and minify assets wherever possible (For CSS/JS, Sprockets and webpack do this for us).
 - If some functionality can reasonably be achieved without adding extra libraries, avoid them.
 - Use page-specific JavaScript as described above to dynamically load libraries that are only needed on certain pages.
+- [High Performance Animations][high-perf-animations]
 
 -------
 
@@ -105,3 +115,5 @@ General tips:
 [d3]: https://d3js.org/
 [chartjs]: http://www.chartjs.org/
 [page-specific-js-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/13bb9ed77f405c5f6ee4fdbc964ecf635c9a223f/app/views/projects/graphs/_head.html.haml#L6-8
+[high-perf-animations]: https://www.html5rocks.com/en/tutorials/speed/high-performance-animations/
+[flip]: https://aerotwist.com/blog/flip-your-animations/