Add latest changes from gitlab-org/gitlab@master

3 files changed, 80 insertions, 17 deletions

diff --git a/doc/development/api_graphql_styleguide.md b/doc/development/api_graphql_styleguide.md
index 7d884737f5b..9e419be9419 100644
--- a/doc/development/api_graphql_styleguide.md
+++ b/doc/development/api_graphql_styleguide.md
@@ -21,6 +21,12 @@ and in [PDF](https://gitlab.com/gitlab-org/create-stage/uploads/8e78ea7f326b2ef6
 Everything covered in this deep dive was accurate as of GitLab 11.9, and while specific
 details may have changed since then, it should still serve as a good introduction.
 
+## GraphiQL
+
+GraphiQL is an interactive GraphQL API explorer where you can play around with existing queries.
+You can access it in any GitLab environment on `https://<your-gitlab-site.com>/-/graphql-explorer`.
+For example, the one for [GitLab.com](https://gitlab.com/-/graphql-explorer).
+
 ## Authentication
 
 Authentication happens through the `GraphqlController`, right now this
@@ -335,7 +341,7 @@ field :id, GraphQL::ID_TYPE, description: 'ID of the resource'
 
 Descriptions of fields and arguments are viewable to users through:
 
-- The [GraphiQL explorer](../api/graphql/#graphiql).
+- The [GraphiQL explorer](#graphiql).
 - The [static GraphQL API reference](../api/graphql/#reference).
 
 ### Description styleguide
diff --git a/doc/development/logging.md b/doc/development/logging.md
index a90d78ba8d9..f10737da766 100644
--- a/doc/development/logging.md
+++ b/doc/development/logging.md
@@ -112,20 +112,57 @@ importer progresses. Here's what to do:
    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):
+#### Implicit schema for JSON logging
+
+When using something like Elasticsearch to index structured logs, there is a
+schema for the types of each log field (even if that schema is implicit /
+inferred). It's important to be consistent with the types of your field values,
+otherwise this might break the ability to search/filter on these fields, or even
+cause whole log events to be dropped. While much of this section is phrased in
+an Elasticsearch-specific way, the concepts should translate to many systems you
+might use to index structured logs. GitLab.com uses Elasticsearch to index log
+data.
+
+Unless a field type is explicitly mapped, Elasticsearch will infer the type from
+the first instance of that field value it sees. Subsequent instances of that
+field value with different types will either fail to be indexed, or in some
+cases (scalar/object conflict), the whole log line will be dropped.
+
+GitLab.com's logging Elasticsearch sets
+[`ignore_malformed`](https://www.elastic.co/guide/en/elasticsearch/reference/current/ignore-malformed.html),
+which allows documents to be indexed even when there are simpler sorts of
+mapping conflict (for example, number / string), although indexing on the affected fields
+will break.
+
+Examples:
 
-   ```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")
 
-   ```ruby
-   # GOOD
-   logger.info(message: "Import error", error_code: 1, error: "I/O failure")
-   ```
+# BAD
+logger.info(message: "Import error", error: 1)
+logger.info(message: "Import error", error: "I/O failure")
+
+# WORST
+logger.info(message: "Import error", error: "I/O failure")
+logger.info(message: "Import error", error: { message: "I/O failure" })
+```
+
+List elements must be the same type:
+
+```ruby
+# GOOD
+logger.info(a_list: ["foo", "1", "true"])
+
+# BAD
+logger.info(a_list: ["foo", 1, true])
+```
+
+Resources:
+
+- [Elasticsearch mapping - avoiding type gotchas](https://www.elastic.co/guide/en/elasticsearch/guide/current/mapping.html#_avoiding_type_gotchas)
+- [Elasticsearch mapping types]( https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-types.html)
 
 ## Multi-destination Logging
 
diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md
index 3f202115b4c..776ac252b76 100644
--- a/doc/development/migration_style_guide.md
+++ b/doc/development/migration_style_guide.md
@@ -176,9 +176,15 @@ Removing a column:
 ```ruby
 include Gitlab::Database::MigrationHelpers
 
-def change
+def up
   with_lock_retries do
-    remove_column :users, :full_name, :string
+    remove_column :users, :full_name
+  end
+end
+
+def down
+  with_lock_retries do
+    add_column :users, :full_name, :string
   end
 end
 ```
@@ -188,11 +194,17 @@ Removing a foreign key:
 ```ruby
 include Gitlab::Database::MigrationHelpers
 
-def change
+def up
   with_lock_retries do
     remove_foreign_key :issues, :projects
   end
 end
+
+def down
+  with_lock_retries do
+    add_foreign_key :issues, :projects
+  end
+end
 ```
 
 Changing default value for a column:
@@ -200,11 +212,17 @@ Changing default value for a column:
 ```ruby
 include Gitlab::Database::MigrationHelpers
 
-def change
+def up
   with_lock_retries do
     change_column_default :merge_requests, :lock_version, from: nil, to: 0
   end
 end
+
+def down
+  with_lock_retries do
+    change_column_default :merge_requests, :lock_version, from: 0, to: nil
+  end
+end
 ```
 
 ### When to use the helper method
@@ -231,6 +249,8 @@ Example changes:
 
 **Note:** `with_lock_retries` method **cannot** be used with `disable_ddl_transaction!`.
 
+**Note:** `with_lock_retries` method **cannot** be used within the `change` method, you must manually define the `up` and `down` methods to make the migration reversible.
+
 ### How the helper method works
 
 1. Iterate 50 times.