Add compatibility guidelines to API documentation

Description

When working on the API, there is no documentation describing a practice, or strategy for backwards compatibility. We should add a section describing how to handle breaking changes. Maybe answer a few questions like:

• When should you ensure backwards compatibility?
• How to track old code/features/methods that can be removed after major versions
• Formalities for upgrading to API versions with breaking changes

Proposal

Add a section or completely new document in https://docs.gitlab.com/ce/api/

Mentioned in merge request gitlab-foss!6355 (closed)

Added ~15078 ~13884 labels

I think this is a good idea. We should add this to the Developer Documentation with more detailed guidelines and then a short section on the API README with a link to the developer documentation if they want more information.

cc: @zj @razer6

Good points, my opinion:

When should you ensure backwards compatibility?

Lets follow SemVer here and not drop any endpoints in a major point release line. Next major point we have the ability to drop a couple of endpoints where needed. What exactly is a bug and can be fixed now already should be decided on a case by case basis.

How to track old code/features/methods that can be removed after major versions

I've created gitlab-org/gitlab-ce#20070 to track all endpoints up for changes. Mind you, this issue is for tracking purposes only, not for discussions if it should be dropped/changed. Thats what the linked issue is for.

Formalities for upgrading to API versions with breaking changes

If the endpoint changes from say: /project/fork/:id to /project/:id/fork we could, and should already support the latter. The former is dropped on the 9.0 release. If its not yet possible to support a new endpoint we shouldn't and change where needed in the next major point release.

@brianp Thanks for asking these questions, if you have more, please ask 😃

moved from gitlab-foss#22693 (moved)