1 files changed, 96 insertions, 0 deletions
diff --git a/doc/development/graphql_guide/reviewing.md b/doc/development/graphql_guide/reviewing.md
new file mode 100644
index 00000000000..9c32179a89d
--- /dev/null
+++ b/doc/development/graphql_guide/reviewing.md
@@ -0,0 +1,96 @@
+---
+stage: none
+group: unassigned
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
+---
+
+# GraphQL API merge request checklist
+
+The GitLab GraphQL API has a fair degree of complexity so it's important that merge requests containing GraphQL changes be reviewed by someone familiar with GraphQL.
+You can ping one via the `@gitlab-org/graphql-experts` group in a MR or in the [`#f_graphql` channel](https://gitlab.slack.com/archives/C6MLS3XEU) in Slack (available to GitLab team members only).
+
+GraphQL queries need to be reviewed for:
+
+- breaking changes
+- authorization
+- performance
+
+## Review criteria
+
+This is not an exhaustive list.
+
+### Description with sample query
+
+Ensure that the description includes a sample query with setup instructions.
+Try running the query in [GraphiQL](../api_graphql_styleguide.md#graphiql) on your local GDK instance.
+
+### No breaking changes (unless after full deprecation cycle)
+
+Check the MR for any [breaking changes](../api_graphql_styleguide.md#breaking-changes).
+
+If a feature is marked as an [Experiment](../api_graphql_styleguide.md#mark-schema-items-as-alpha), you can make breaking changes immediately, with no deprecation period.
+
+For more information, see [deprecation and removal process](../../api/graphql/index.md#deprecation-and-removal-process).
+
+### Multiversion compatibility
+
+Ensure that multi-version compatibility is guaranteed.
+This generally means frontend and backend code for the same GraphQL feature can't be shipped in the same release.
+
+For details, see [multiple version compatibility](../multi_version_compatibility.md).
+
+### Technical writing review
+
+Changes to the generated API docs require a technical writer review.
+
+### Changelog
+
+Public-facing changes that are not marked as an [Experiment](../api_graphql_styleguide.md#mark-schema-items-as-alpha) require a [changelog entry](../changelog.md).
+
+### Use the framework
+
+GraphQL is a framework with many moving parts. It's important that the framework is followed.
+
+- Do not manually invoke framework bits. For example, do not instantiate resolvers during execution and instead let the framework do that.
+- You can subclass resolvers, as in `MyResolver.single` (see [deriving resolvers](../api_graphql_styleguide.md#deriving-resolvers)).
+- Use the `ready?` method for more complex argument logic (see [correct use of resolver#ready](../api_graphql_styleguide.md#correct-use-of-resolverready)).
+- Use the `prepare` method for more complex argument validation (see [validating arguments](../api_graphql_styleguide.md#validating-arguments)).
+
+For details, see [resolver guide](../api_graphql_styleguide.md#writing-resolvers).
+
+### Authorization
+
+Ensure proper authorization is followed and that `authorize :some_ability` is tested in the specs.
+
+For details, see [authorization guide](authorization.md).
+
+### Performance
+
+Ensure:
+
+- You avoid N+1s with [BatchLoader](batchloader.md) or [Lookahead](../api_graphql_styleguide.md#look-ahead) when appropriate.
+- You use [laziness](../api_graphql_styleguide.md#laziness) appropriately.
+
+### Use appropriate types
+
+For example:
+
+- [`TimeType`](../api_graphql_styleguide.md#typestimetype) for Ruby `Time` and `DateTime` objects.
+- Global IDs for `id` fields
+
+For details, see [types](../api_graphql_styleguide.md#types).
+
+### Appropriate complexity
+
+Query complexity is a way of quantifying how expensive a query is likely to be. Query complexity limits are defined as constants in the schema.
+When a resolver or type is expensive to call we need to ensure that the query complexity reflects that.
+
+For details, see [max complexity](../api_graphql_styleguide.md#max-complexity), [field complexity](../api_graphql_styleguide.md#field-complexity) and [query limits](../api_graphql_styleguide.md#query-limits).
+
+### Testing
+
+- Resolver (unit) specs are deprecated in favour of request (integration) specs.
+- Many aspects of our framework are outside the `resolve` method and a request spec is the only way to ensure they behave properly.
+- Every GraphQL change MR should ideally have changes to API specs.
+
+For details, see [testing guide](../api_graphql_styleguide.md#testing).