Add latest changes from gitlab-org/gitlab@master

1 files changed, 15 insertions, 11 deletions

diff --git a/doc/development/api_graphql_styleguide.md b/doc/development/api_graphql_styleguide.md
index f32aaf6ffa8..54e2cb9c68d 100644
--- a/doc/development/api_graphql_styleguide.md
+++ b/doc/development/api_graphql_styleguide.md
@@ -490,15 +490,18 @@ def foo
 end
 ```
 
-## Deprecating fields and enum values
+## Deprecating fields, arguments, and enum values
 
 The GitLab GraphQL API is versionless, which means we maintain backwards
-compatibility with older versions of the API with every change. Rather
-than removing a field or [enum value](#enums), we need to _deprecate_ it instead.
+compatibility with older versions of the API with every change.
+
+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).
 
-Fields and enum values are deprecated using the `deprecated` property.
+Fields, arguments, and enum values are deprecated using the `deprecated` property.
 The value of the property is a `Hash` of:
 
 - `reason` - Reason for the deprecation.
@@ -518,14 +521,15 @@ is appended to the `description`.
 
 ### Deprecation reason style guide
 
-Where the reason for deprecation is due to the field or enum value being
-replaced, the `reason` must be:
+Where the reason for deprecation is due to the field, argument, or enum value being
+replaced, the `reason` must indicate the replacement. For example, the
+following is a `reason` for a replaced field:
 
 ```plaintext
 Use `otherFieldName`
 ```
 
-Example:
+Examples:
 
 ```ruby
 field :designs, ::Types::DesignManagement::DesignCollectionType, null: true,
@@ -544,8 +548,8 @@ module Types
 end
 ```
 
-If the field is not being replaced by another field, a descriptive
-deprecation `reason` should be given.
+If the field, argument, or enum value being deprecated is not being replaced,
+a descriptive deprecation `reason` should be given.
 
 See also [Aliasing and deprecating mutations](#aliasing-and-deprecating-mutations).
 
@@ -594,7 +598,7 @@ end
 ```
 
 Enum values can be deprecated using the
-[`deprecated` keyword](#deprecating-fields-and-enum-values).
+[`deprecated` keyword](#deprecating-fields-arguments-and-enum-values).
 
 ### Defining GraphQL enums dynamically from Rails enums
 
@@ -1567,7 +1571,7 @@ mount_aliased_mutation 'BarMutation', Mutations::FooMutation
 ```
 
 This allows us to rename a mutation and continue to support the old name,
-when coupled with the [`deprecated`](#deprecating-fields-and-enum-values)
+when coupled with the [`deprecated`](#deprecating-fields-arguments-and-enum-values)
 argument.
 
 Example: