diff --git a/doc/development/multi_version_compatibility.md b/doc/development/multi_version_compatibility.md
index 9e89186fb1ae982e08ea9bd7b4fb05a1434b1b3f..cef0bbf971068124ad773d739b74029713823a89 100644
--- a/doc/development/multi_version_compatibility.md
+++ b/doc/development/multi_version_compatibility.md
@@ -22,13 +22,21 @@ For example when [changing arguments](sidekiq/compatibility_across_updates.md#ch
 
 Is it ok if these jobs don't get executed for several hours because [Sidekiq nodes are not yet updated](sidekiq/compatibility_across_updates.md#adding-new-workers)?
 
-### When modifying JavaScript
+### When modifying JavaScript/Vue
 
-Is it ok when a browser has the new JavaScript code, but the Rails code is running the previous monthly release on:
+Is it ok when a browser has the new JavaScript code, but the REST API or GraphQL API is running the previous monthly release?
 
-- the REST API?
-- the GraphQL API?
-- internal APIs in controllers?
+#### GitLab.com
+
+Yes, if the backend MR is merged and deployed before the frontend MR. You cannot put backend and frontend GraphQL or REST API changes in the same MR. The frontend usage should also be guarded by a feature flag or be able to fail gracefully. See self-managed section below for more information.
+
+#### Self-managed
+
+When adding GraphQL queries or mutations you need to wait one milestone before using on the frontend. For example if you add a GraphQL query in 18.3 you need to wait until 18.4 to use that query on the frontend. You can use the GraphQL query or mutation on the frontend behind a feature flag but it cannot be default enabled in the same milestone it was added.
+
+When adding GraphQL fields to an existing query you can use the [`@gl_introduced` directive](api_graphql_styleguide.md#mitigation).
+
+When adding fields to REST APIs you can fallback to the old field if the new field doesn't exist in the response.
 
 ### When adding a pre-deployment migration