Merge remote-tracking branch 'upstream/master' into 1819-override-ce

* upstream/master: (621 commits)
  Add a note about GitLab QA page objects validator to docs
  Refactor dispatcher projects blame and blob path
  Update export message to mention we can download the file from the UI
  Fix Ctrl+Enter keyboard shortcut saving comment/note edit
  fix case where tooltip messes up :last-child selector
  Add reason to keep postgresql 9.2 for CI
  Remove warning noise in ProjectImportOptions
  Add changelog entry
  Add RedirectRoute factory
  Update Ingress extra cost note to be more generic
  Fix Rubocop offense
  Refactor dispatcher project branches path
  Revert "Revert "Fix Route validation for unchanged path""
  Document that we need rsync for backing up
  Docs: move article "Laravel and Envoy w/ CI/CD"
  Recommend against the use of EFS
  Adds Rubocop rule for line break around conditionals
  Update CHANGELOG.md for 10.1.6
  Filter out build traces from logged parameters
  Refactored project:n* imports in dispatcher.js
  ...

1 files changed, 92 insertions, 0 deletions

diff --git a/doc/development/utilities.md b/doc/development/utilities.md
new file mode 100644
index 00000000000..951c3ef85ce
--- /dev/null
+++ b/doc/development/utilities.md
@@ -0,0 +1,92 @@
+# GitLab utilities
+
+We developed a number of utilities to ease development.
+
+## [`MergeHash`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/gitlab/utils/merge_hash.rb)
+
+* Deep merges an array of hashes:
+
+    ``` ruby
+    Gitlab::Utils::MergeHash.merge(
+      [{ hello: ["world"] },
+       { hello: "Everyone" },
+       { hello: { greetings: ['Bonjour', 'Hello', 'Hallo', 'Dzien dobry'] } },
+        "Goodbye", "Hallo"]
+    )
+    ```
+
+    Gives:
+
+    ``` ruby
+    [
+      {
+        hello:
+          [
+            "world",
+            "Everyone",
+            { greetings: ['Bonjour', 'Hello', 'Hallo', 'Dzien dobry'] }
+          ]
+      },
+      "Goodbye"
+    ]
+    ```
+
+* Extracts all keys and values from a hash into an array:
+
+    ``` ruby
+    Gitlab::Utils::MergeHash.crush(
+      { hello: "world", this: { crushes: ["an entire", "hash"] } }
+    )
+    ```
+
+    Gives:
+
+    ``` ruby
+    [:hello, "world", :this, :crushes, "an entire", "hash"]
+    ```
+
+## [`StrongMemoize`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/gitlab/utils/strong_memoize.rb)
+
+* Memoize the value even if it is `nil` or `false`.
+
+    We often do `@value ||= compute`, however this doesn't work well if
+    `compute` might eventually give `nil` and we don't want to compute again.
+    Instead we could use `defined?` to check if the value is set or not.
+    However it's tedious to write such pattern, and `StrongMemoize` would
+    help us use such pattern.
+
+    Instead of writing patterns like this:
+
+    ``` ruby
+    class Find
+      def result
+        return @result if defined?(@result)
+
+        @result = search
+      end
+    end
+    ```
+
+    We could write it like:
+
+    ``` ruby
+    class Find
+      include Gitlab::Utils::StrongMemoize
+
+      def result
+        strong_memoize(:result) do
+          search
+        end
+      end
+    end
+    ```
+
+* Clear memoization
+
+    ``` ruby
+    class Find
+      include Gitlab::Utils::StrongMemoize
+    end
+
+    Find.new.clear_memoization(:result)
+    ```