Merge branch 'ld-clarify-complexity-and-breaking-changes' into 'master'

Clarify breaking changes in GraphQL docs

See merge request gitlab-org/gitlab!53176

doc/api/graphql/index.md

@@ -65,27 +65,49 @@ There are no plans to deprecate the REST API. To reduce the technical burden of
 supporting two APIs in parallel, they should share implementations as much as
 possible.
 
-### Deprecation process
+## Breaking changes
 
-Fields marked for removal from the GitLab GraphQL API are first **deprecated** but still available
-for at least six releases, and then **removed entirely**.
-Removals occur at X.0 and X.6 releases.
+The GitLab GraphQL API is [versionless](https://graphql.org/learn/best-practices/#versioning) and
+changes are made to the API in a way that maintains backwards-compatibility.
 
-For example, a field can be marked as deprecated (but still usable) in %12.7, but can be used until its removal in %13.6.
-When marked as deprecated, an alternative should be provided if there is one.
-That gives consumers of the GraphQL API a minimum of six months to update their GraphQL queries.
+Occassionally GitLab needs to change the GraphQL API in a way that is not backwards-compatible.
+These changes include the removal or renaming of fields, arguments or other parts of the schema.
 
-The process is as follows:
+In these situations, GitLab follows a [Deprecation and removal process](#deprecation-and-removal-process)
+where the deprecated part of the schema is supported for a period of time before being removed.
 
-1. The field is listed as deprecated in [GraphQL API Reference](reference/index.md).
-1. Removals are announced at least one release prior in the Deprecation Warnings section of the
-   release post (at or prior to X.11 and X.5 releases).
-1. Fields meeting criteria are removed in X.0 or X.6.
+Clients should familiarize themselves with the process to avoid breaking changes affecting their integrations.
 
 NOTE:
 Fields behind a feature flag and disabled by default are exempt from the deprecation process,
 and can be removed at any time without notice.
 
+### Deprecation and Removal process
+
+Parts of the schema marked for removal from the GitLab GraphQL API are first **deprecated** but still available
+for at least six releases, and then **removed entirely**.
+Removals occur at `X.0` and `X.6` releases.
+
+The process is as follows:
+
+1. The item is marked as deprecated in the schema. It will be displayed as deprecated in the
+   [GraphQL API Reference](reference/index.md) and in introspection queries.
+1. Removals are announced at least one release prior in the [Deprecations](https://about.gitlab.com/handbook/marketing/blog/release-posts/#deprecations)
+   section of the release post (at or prior to `X.11` and `X.5` releases).
+   release post (at or prior to `X.11` and `X.5` releases).
+1. Items meeting criteria are removed in `X.0` or `X.6` and added to:
+
+   - The [Removals](https://about.gitlab.com/handbook/marketing/blog/release-posts/#removals) section of the Release Post.
+   - The [Removed items page](removed_items.md).
+
+This gives consumers of the GraphQL API a minimum of six months to update their GraphQL queries.
+
+When an item is deprecated or removed, an alternative is provided if available.
+
+**Example:**
+
+A field marked as deprecated in `12.7` can be used until its removal in `13.6`.
+
 ### List of removed items
 
 View the [fields, enums, and other items we removed](removed_items.md) from the GraphQL API.
@@ -147,8 +169,10 @@ In general, each field in a query will add `1` to the complexity score, although
 this can be higher or lower for particular fields. Sometimes the addition of
 certain arguments may also increase the complexity of a query.
 
+NOTE:
 The complexity limits may be revised in future, and additionally, the complexity
-of a query may be altered.
+of a query may be altered. Changes to complexity can happen on `X.0` or `X.6`
+releases without a deprecation period.
 
 ### Request timeout
 

doc/api/graphql/reference/index.md

@@ -21,7 +21,7 @@ fields and methods on a model are available via GraphQL.
 
 WARNING:
 Fields that are deprecated are marked with **{warning-solid}**.
-Items (fields, enums, etc) that have been removed according to our [deprecation process](../index.md#deprecation-process) can be found
+Items (fields, enums, etc) that have been removed according to our [deprecation process](../index.md#deprecation-and-removal-process) can be found
 in [Removed Items](../removed_items.md).
 
 <!-- vale gitlab.Spelling = NO -->

doc/api/graphql/removed_items.md

@@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 GraphQL is a versionless API, unlike the REST API.
 Occasionally, items have to be updated or removed from the GraphQL API.
-According to our [process for removing items](index.md#deprecation-process), here are the items that have been removed.
+According to our [process for removing items](index.md#deprecation-and-removal-process), here are the items that have been removed.
 
 ## GitLab 13.6
 

doc/development/api_graphql_styleguide.md

@@ -76,6 +76,25 @@ Rake task.
 
 Requests time out at 30 seconds.
 
+## Breaking changes
+
+The GitLab GraphQL API is [versionless](https://graphql.org/learn/best-practices/#versioning) which means
+developers must familiarize themselves with our [deprecation cycle of breaking changes](#breaking-changes).
+
+Breaking changes are:
+
+- Removing or renaming a field, argument, enum value or mutation.
+- Changing the type of a field, argument or enum value.
+- Raising the [complexity](#max-complexity) of a field or complexity multipliers in a resolver.
+- Changing the [max page size](#page-size-limit) of a connection.
+- Lowering the global limits for query complexity and depth.
+- Anything else that can result in queries hitting a limit that previously was allowed.
+
+Fields that use the [`feature_flag` property](#feature_flag-property) and the flag is disabled by default are exempt
+from the deprecation process, and can be removed at any time without notice.
+
+See the [deprecating fields and enum values](#deprecating-fields-arguments-and-enum-values) section for how to deprecate items.
+
 ## Global IDs
 
 The GitLab GraphQL API uses Global IDs (i.e: `"gid://gitlab/MyObject/123"`)
@@ -499,7 +518,7 @@ Rather than removing fields, arguments, or [enum values](#enums), they
 must be _deprecated_ instead.
 
 The deprecated parts of the schema can then be removed in a future release
-in accordance with the [GitLab deprecation process](../api/graphql/index.md#deprecation-process).
+in accordance with the [GitLab deprecation process](../api/graphql/index.md#deprecation-and-removal-process).
 
 Fields, arguments, and enum values are deprecated using the `deprecated` property.
 The value of the property is a `Hash` of:

doc/development/changelog.md

@@ -45,7 +45,7 @@ the `author` field. GitLab team members **should not**.
   **must** have a changelog entry, without `merge_request` value
   and with `type` set to `security`.
 - Any user-facing change **must** have a changelog entry. This includes both visual changes (regardless of how minor), and changes to the rendered DOM which impact how a screen reader may announce the content.
-- Any client-facing change to our REST and GraphQL APIs **must** have a changelog entry. This includes modifying complexity of GraphQL fields.
+- Any client-facing change to our REST and GraphQL APIs **must** have a changelog entry. See the [complete list what comprises a GraphQL breaking change](api_graphql_styleguide.md#breaking-changes).
 - Performance improvements **should** have a changelog entry.
 - Changes that need to be documented in the Product Intelligence [Event Dictionary](https://about.gitlab.com/handbook/product/product-intelligence-guide/#event-dictionary)
   also require a changelog entry.

lib/gitlab/graphql/docs/templates/default.md.haml

@@ -14,7 +14,7 @@
 
   WARNING:
   Fields that are deprecated are marked with **{warning-solid}**.
-  Items (fields, enums, etc) that have been removed according to our [deprecation process](../index.md#deprecation-process) can be found
+  Items (fields, enums, etc) that have been removed according to our [deprecation process](../index.md#deprecation-and-removal-process) can be found
   in [Removed Items](../removed_items.md).
 
   <!-- vale gitlab.Spelling = NO -->