- Review criteria
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 in Slack (available to GitLab team members only).
GraphQL queries need to be reviewed for:
- breaking changes
This is not an exhaustive list.
Ensure that the description includes a sample query with setup instructions. Try running the query in GraphiQL on your local GDK instance.
Check the MR for any breaking changes.
If a feature is marked as an Experiment, you can make breaking changes immediately, with no deprecation period.
For more information, see deprecation and removal process.
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.
Changes to the generated API docs require a technical writer review.
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).
- Use the
ready?method for more complex argument logic (see correct use of resolver#ready).
- Use the
preparemethod for more complex argument validation (see validating arguments).
For details, see resolver guide.
Ensure proper authorization is followed and that
authorize :some_ability is tested in the specs.
For details, see authorization guide.
- You have checked for N+1s and used optimizations to remove N+1s whenever possible.
- You use laziness appropriately.
- Global IDs for
For details, see types.
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.
- Resolver (unit) specs are deprecated in favour of request (integration) specs.
- Many aspects of our framework are outside the
resolvemethod 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.