Add section to GraphQL developer docs about how to deprecate

We should add a section to the GraphQL developer docs to guide developers on deprecation best practices for the GraphQL schema.

Sections

Some ideas:

• What deprecating is
• How to deprecate (see Standards)
  • Example code
• How to avoid deprecation
• Mention about our upcoming plans to remove deprecated fields gitlab-com/Product#507 (closed)

Standards

deprecation_reason

deprecation_reason: '<reason-for-deprecation>. Deprecated in <GitLab version>'
# e.g.:
deprecation_reason: 'Plain text token has been masked for security reasons. Deprecated in 12.8'

Where the field is being replaced with another one, <reason-for-deprecation> should specifically be:

Use `<other-field-name>`

# e.g.:
deprecation_reason: 'Use `pipelines`. Deprecated in 12.8'

description

description: '<existing description>. Deprecated in <GitLab version>: <reason-for-deprecation>'
# e.g.:
description: 'API token for the Grafana integration. Deprecated in 12.8: Plain text token has been masked for security reasons'
description: 'Latest pipeline of the commit. Deprecated in 12.8: Use `pipelines`'