diff --git a/doc/api/graphql/index.md b/doc/api/graphql/index.md index 726c448c33b31d6468bf89fc52632fb00c0e8e67..7057bb684877db28a572fbf3f1b941fe27dc677b 100644 --- a/doc/api/graphql/index.md +++ b/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 diff --git a/doc/api/graphql/reference/index.md b/doc/api/graphql/reference/index.md index 059c2985d8b6b73f96447142be508b0539f4cb09..9e4438d2dbff1031b972ca329bc2c6075f69e3e0 100644 --- a/doc/api/graphql/reference/index.md +++ b/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 --> diff --git a/doc/api/graphql/removed_items.md b/doc/api/graphql/removed_items.md index 2761c1a1c8488df93b0a458baddc5fb35a252536..a76f1fb74184d1a94db1882bc043a192b2c75b5d 100644 --- a/doc/api/graphql/removed_items.md +++ b/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 diff --git a/doc/development/api_graphql_styleguide.md b/doc/development/api_graphql_styleguide.md index 54e2cb9c68d6117e237c207aed1fdc56bf67e072..c8e32d8d0895eac30ccf626cbb348556a9ef7162 100644 --- a/doc/development/api_graphql_styleguide.md +++ b/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: diff --git a/doc/development/changelog.md b/doc/development/changelog.md index 44be6e9548b11fbdf7fcc5dc7bc4d5463bd28867..fa771f9625968e7d5e6620ad2701f1eb728c54a4 100644 --- a/doc/development/changelog.md +++ b/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. diff --git a/lib/gitlab/graphql/docs/templates/default.md.haml b/lib/gitlab/graphql/docs/templates/default.md.haml index 1df1c3a3e58dcb90a3ca208a710571c4a1da9416..68df4934a09153bc6fd7b4ba26a78dcf39641a7a 100644 --- a/lib/gitlab/graphql/docs/templates/default.md.haml +++ b/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 -->