Document compatibility process for the HTTP API

GitLab lacked formal documentation around our API, how the versioning
worked and to the numbers meant.

Fixes https://gitlab.com/gitlab-org/gitlab-ce/issues/22693

1 files changed, 23 insertions, 0 deletions

diff --git a/doc/api/README.md b/doc/api/README.md
index ae4481b400e..66e1df41cf6 100644
--- a/doc/api/README.md
+++ b/doc/api/README.md
@@ -85,6 +85,29 @@ have been resolved to our satisfaction by the relicensing of the reference
 implementations under MIT, and the use of the OWF license for the GraphQL
 specification.
 
+## Compatibility Guidelines
+
+The HTTP API is versioned using a single number, the current one being 4. This
+number symbolises the same as the major version number as described by 
+[SemVer](https://semver.org/). This mean that backward incompatible changes
+will require this version number to change. However, the minor version is
+not explicit. This allows for a stable API endpoint, but also means new 
+features can be added to the API in the same version number.
+
+New features and bug fixes are released in tandem with a new GitLab, and apart
+from incidental patch and security releases, are released on the 22nd each
+month. Backward incompatible changes (e.g. endpoints removal, parameters 
+removal etc.), as well as removal of entire API versions are done in tandem 
+with a major point release of GitLab itself. All deprecations and changes 
+between two versions should be listed in the documentation. For the changes 
+between v3 and v4; please read the [v3 to v4 documentation](v3_to_v4.md)
+
+#### Current status
+
+Currently two API versions are available, v3 and v4. v3 is deprecated and 
+will soon be removed. Deletion is scheduled for 
+[GitLab 11.0](https://gitlab.com/gitlab-org/gitlab-ce/issues/36819).
+
 ## Basic usage
 
 API requests should be prefixed with `api` and the API version. The API version