Merge branch 'ld-graphql-docs-mutation-naming-conventions' into 'master'

[Docs] Expand GraphQL mutation naming conventions

See merge request gitlab-org/gitlab!34584

doc/development/api_graphql_styleguide.md

@@ -717,11 +717,49 @@ will be returned as the result of the mutation.
 
 ### Naming conventions
 
-Always provide a consistent GraphQL-name to the mutation, this name is
-used to generate the input types and the field the mutation is mounted
-on. The name should look like `<Resource being modified><Mutation
-class name>`, for example the `Mutations::MergeRequests::SetWip`
-mutation has GraphQL name `MergeRequestSetWip`.
+Each mutation must define a `graphql_name`, which is the name of the
+mutation in the GraphQL schema.
+
+Example:
+
+```ruby
+class UserUpdateMutation < BaseMutation
+  graphql_name 'UserUpdate'
+end
+```
+
+Our GraphQL mutation names are historically inconsistent, but new
+mutation names should follow the convention `'{Resource}{Action}'`
+or `'{Resource}{Action}{Attribute}'`.
+
+Mutations that **create** new resources should use the verb `Create`.
+
+Example:
+
+- `CommitCreate`
+
+Mutations that **update** data should use the verb `Update` or a
+domain-specific verb like `Set`, `Add`, or `Toggle` if more
+appropriate.
+
+Examples:
+
+- `EpicTreeReorder`
+- `IssueSetWeight`
+- `IssueUpdate`
+- `TodoMarkDone`
+
+Mutations that **remove** data should use the verb `Delete` rather than
+`Destroy`. Or use a domain-specific verb like `Remove` if more
+appropriate.
+
+Examples:
+
+- `AwardEmojiRemove`
+- `NoteDelete`
+
+If you need advice for mutation naming, canvass the Slack `#graphql`
+channel for feedback.
 
 ### Arguments