Clarify in https://docs.gitlab.com/ee/development/deprecation_guidelines the deprecation and breaking change guidelines for APIs
This issue came out of this discussion https://gitlab.com/gitlab-org/manage/manage-workspace/discussions/-/issues/40#note_1101575358.
The https://docs.gitlab.com/ee/development/deprecation_guidelines/ can be improved for our APIs:
- For breaking change section, link directly to https://docs.gitlab.com/ee/development/api_graphql_styleguide.html#breaking-changes for GraphQL and the outcome of #373775 (closed) for REST.
- Highlight here https://docs.gitlab.com/ee/development/deprecation_guidelines/#when-can-a-feature-be-removedchanged that breaking changes are made on new versions of the REST API, rather than on major versions of GitLab. With this caveat: #373774 (closed).
- Hightlight that API v4 deprecations that are to be removed in v5 are not really deprecations, and should not have a deprecation entry #350534 (comment 1118451148).
- Hightlight that soft breaking changes can be scheduled and announced in deprecation entries for REST v4 and GraphQL #373775 (closed).
Edited by Luke Duncalfe