From bb383c0bb24dc1f86ddb61cda21e3f8aefef990b Mon Sep 17 00:00:00 2001 From: Peter Hegman Date: Wed, 3 Sep 2025 20:51:57 -0700 Subject: [PATCH 1/3] Add clarification about backwards compatibility of API changes --- doc/development/multi_version_compatibility.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/doc/development/multi_version_compatibility.md b/doc/development/multi_version_compatibility.md index 9e89186fb1ae98..3e877fb90a074b 100644 --- a/doc/development/multi_version_compatibility.md +++ b/doc/development/multi_version_compatibility.md @@ -111,6 +111,20 @@ Many users skip some monthly releases, for example: These users accept some downtime during the update. Unfortunately we can't ignore this case completely. For example, 13.12 may execute Sidekiq jobs from 13.0, which illustrates why [we avoid removing arguments from jobs until a major release](sidekiq/compatibility_across_updates.md#deprecate-and-remove-an-argument). The main question is: Will the deployment get to a good state after the update is complete? +## Can I use a GraphQL or REST API change on the frontend in the same milestone it is added? + +### On 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 gracefuly. See self-manged section below for more informaiton. + +### For self-managed releases + +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. + +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 doens't exist in the response. + ## What kind of components can GitLab be broken down into? The [1000 RPS or 50,000 user reference architecture](../administration/reference_architectures/50k_users.md) runs GitLab on 48+ nodes. GitLab.com is [bigger than that](https://handbook.gitlab.com/handbook/engineering/infrastructure/production/architecture/), plus a portion of the [infrastructure runs on Kubernetes](https://handbook.gitlab.com/handbook/engineering/infrastructure/production/architecture/#gitlab-com-architecture), plus there is a ["canary" stage which receives updates first](https://handbook.gitlab.com/handbook/engineering/infrastructure/environments/canary-stage/). -- GitLab From 0f4c84c603532b539b0d6cc69b66f2e1732451dd Mon Sep 17 00:00:00 2001 From: Peter Hegman Date: Wed, 17 Sep 2025 14:21:43 -0700 Subject: [PATCH 2/3] Address reviewer feedback - Fix a few typos - Clarify usage on self-managed behind feature flags --- doc/development/multi_version_compatibility.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/development/multi_version_compatibility.md b/doc/development/multi_version_compatibility.md index 3e877fb90a074b..4abd77749557f3 100644 --- a/doc/development/multi_version_compatibility.md +++ b/doc/development/multi_version_compatibility.md @@ -113,17 +113,17 @@ These users accept some downtime during the update. Unfortunately we can't ignor ## Can I use a GraphQL or REST API change on the frontend in the same milestone it is added? -### On GitLab.com +### 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 gracefuly. See self-manged section below for more informaiton. +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. -### For self-managed releases +### 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. +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 doens't exist in the response. +When adding fields to REST APIs you can fallback to the old field if the new field doesn't exist in the response. ## What kind of components can GitLab be broken down into? -- GitLab From 2377e9a07ff4cc60726f089edfd4e74c68d638b4 Mon Sep 17 00:00:00 2001 From: Peter Hegman Date: Tue, 21 Oct 2025 14:06:51 -0700 Subject: [PATCH 3/3] Move to "Common gotchas" section --- .../multi_version_compatibility.md | 32 ++++++++----------- 1 file changed, 13 insertions(+), 19 deletions(-) diff --git a/doc/development/multi_version_compatibility.md b/doc/development/multi_version_compatibility.md index 4abd77749557f3..cef0bbf9710681 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 @@ -111,20 +119,6 @@ Many users skip some monthly releases, for example: These users accept some downtime during the update. Unfortunately we can't ignore this case completely. For example, 13.12 may execute Sidekiq jobs from 13.0, which illustrates why [we avoid removing arguments from jobs until a major release](sidekiq/compatibility_across_updates.md#deprecate-and-remove-an-argument). The main question is: Will the deployment get to a good state after the update is complete? -## Can I use a GraphQL or REST API change on the frontend in the same milestone it is added? - -### 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. - ## What kind of components can GitLab be broken down into? The [1000 RPS or 50,000 user reference architecture](../administration/reference_architectures/50k_users.md) runs GitLab on 48+ nodes. GitLab.com is [bigger than that](https://handbook.gitlab.com/handbook/engineering/infrastructure/production/architecture/), plus a portion of the [infrastructure runs on Kubernetes](https://handbook.gitlab.com/handbook/engineering/infrastructure/production/architecture/#gitlab-com-architecture), plus there is a ["canary" stage which receives updates first](https://handbook.gitlab.com/handbook/engineering/infrastructure/environments/canary-stage/). -- GitLab