Add latest changes from gitlab-org/gitlab@master

2 files changed, 24 insertions, 36 deletions

diff --git a/doc/development/background_migrations.md b/doc/development/background_migrations.md
index 5e16f83b63c..8a1db615022 100644
--- a/doc/development/background_migrations.md
+++ b/doc/development/background_migrations.md
@@ -10,11 +10,6 @@ migrations automatically reschedule themselves for a later point in time.
 
 ## When To Use Background Migrations
 
-> **Note:**
-> When adding background migrations _you must_ make sure they are announced in the
-> monthly release post along with an estimate of how long it will take to complete
-> the migrations.
-
 In the vast majority of cases you will want to use a regular Rails migration
 instead. Background migrations should be used when migrating _data_ in
 tables that have so many rows this process would take hours when performed in a
@@ -34,6 +29,11 @@ Some examples where background migrations can be useful:
 - Populating one column based on JSON stored in another column.
 - Migrating data that depends on the output of external services (e.g. an API).
 
+> **Note:**
+> If the background migration is part of an important upgrade, make sure it's announced
+> in the release post. Discuss with your Project Manager if you're not sure the migration falls
+> into this category.
+
 ## Isolation
 
 Background migrations must be isolated and can not use application code (e.g.
diff --git a/doc/development/fe_guide/graphql.md b/doc/development/fe_guide/graphql.md
index 40df5f3265a..40b9fdef76e 100644
--- a/doc/development/fe_guide/graphql.md
+++ b/doc/development/fe_guide/graphql.md
@@ -39,43 +39,31 @@ To distinguish queries from mutations and fragments, the following naming conven
 - `addUser.mutation.graphql` for mutations;
 - `basicUser.fragment.graphql` for fragments.
 
-GraphQL:
-
-- Queries are stored in `(ee/)app/assets/javascripts/` under the feature. For example, `respository/queries`. Frontend components can use these stored queries.
-- Mutations are stored in
-  `(ee/)app/assets/javascripts/<subfolders>/<name of mutation>.mutation.graphql`.
-
 ### Fragments
 
-Fragments are a way to make your complex GraphQL queries more readable and re-usable.
-They can be stored in a separate file and imported.
+Fragments are a way to make your complex GraphQL queries more readable and re-usable. Here is an example of GraphQL fragment:
 
-For example, a fragment that references another fragment:
-
-```ruby
-fragment BaseEpic on Epic {
+```javascript
+fragment DesignListItem on Design {
   id
-  iid
-  title
-  webPath
-  relativePosition
-  userPermissions {
-    adminEpic
-    createEpic
-  }
+  image
+  event
+  filename
+  notesCount
 }
+```
 
-fragment EpicNode on Epic {
-  ...BaseEpic
-  state
-  reference(full: true)
-  relationPath
-  createdAt
-  closedAt
-  hasChildren
-  hasIssues
-  group {
-    fullPath
+Fragments can be stored in separate files, imported and used in queries, mutations or other fragments.
+
+```javascript
+#import "./designList.fragment.graphql"
+#import "./diffRefs.fragment.graphql"
+
+fragment DesignItem on Design {
+  ...DesignListItem
+  fullPath
+  diffRefs {
+    ...DesignDiffRefs
   }
 }
 ```