From ae58ccb33c2fb1df8c554b4a7a3ad98210b441db Mon Sep 17 00:00:00 2001 From: Andy Schoenen Date: Thu, 5 Jun 2025 12:06:58 +0200 Subject: [PATCH 1/8] Add exceptions to API breaking changes guide --- doc/development/api_styleguide.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/doc/development/api_styleguide.md b/doc/development/api_styleguide.md index b895ec0e1b1a74..92475fcb1ccac5 100644 --- a/doc/development/api_styleguide.md +++ b/doc/development/api_styleguide.md @@ -81,6 +81,15 @@ The current REST API version is `4`. Because [we commit to follow semantic versi The exception is API features that are [marked as experimental or beta](#experimental-beta-and-generally-available-features). These features can be removed or changed at any time. +### Exceptions to breaking changes policy + +While we commit to maintaining API stability, there are limited circumstances where breaking changes may be necessary: + +1. **Security fixes**: If a breaking change is necessary as part of a security fix, we may make the change to protect users and their data. In such cases, we will: + - Document the change thoroughly in the API documentation. + - Provide migration guidance for API consumers. + - Consider return a `404` status with a message providing a reason for the breaking change and point to the documentation. + ### What to do instead of a breaking change The following sections suggest alternatives to making breaking changes. -- GitLab From 7be0bd2947777e4a3d6abde4db2ddbdf1a941dec Mon Sep 17 00:00:00 2001 From: Andy Schoenen Date: Tue, 17 Jun 2025 11:05:18 +0200 Subject: [PATCH 2/8] Apply review feedback --- doc/development/api_styleguide.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/development/api_styleguide.md b/doc/development/api_styleguide.md index 92475fcb1ccac5..b147bbaf4adc82 100644 --- a/doc/development/api_styleguide.md +++ b/doc/development/api_styleguide.md @@ -88,8 +88,10 @@ While we commit to maintaining API stability, there are limited circumstances wh 1. **Security fixes**: If a breaking change is necessary as part of a security fix, we may make the change to protect users and their data. In such cases, we will: - Document the change thoroughly in the API documentation. - Provide migration guidance for API consumers. - - Consider return a `404` status with a message providing a reason for the breaking change and point to the documentation. + - Ensure the instead of removed behavior, API endpoint returns a `403 Forbidden` response with a message that provides a reason for the breaking change and points to the documentation. + - Keep the `403 Forbidden` response with the message until the next major GitLab version is released. +Example: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/190512 ### What to do instead of a breaking change The following sections suggest alternatives to making breaking changes. -- GitLab From c6a34fcaa0bf2b1b37d87212944c1b336515c34e Mon Sep 17 00:00:00 2001 From: Andy Schoenen Date: Tue, 17 Jun 2025 11:12:08 +0200 Subject: [PATCH 3/8] Apply review suggestion --- doc/development/api_styleguide.md | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/development/api_styleguide.md b/doc/development/api_styleguide.md index b147bbaf4adc82..721353ca449ebd 100644 --- a/doc/development/api_styleguide.md +++ b/doc/development/api_styleguide.md @@ -90,6 +90,7 @@ While we commit to maintaining API stability, there are limited circumstances wh - Provide migration guidance for API consumers. - Ensure the instead of removed behavior, API endpoint returns a `403 Forbidden` response with a message that provides a reason for the breaking change and points to the documentation. - Keep the `403 Forbidden` response with the message until the next major GitLab version is released. + - Create a new issue to delete the `403 Forbidden` response and set the milestone. Example: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/190512 ### What to do instead of a breaking change -- GitLab From 21b54fcfe0565ef81e8a73ad33e743ed6b53800a Mon Sep 17 00:00:00 2001 From: Bogdan Denkovych Date: Tue, 17 Jun 2025 13:12:02 +0300 Subject: [PATCH 4/8] Add empty line before new section --- doc/development/api_styleguide.md | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/development/api_styleguide.md b/doc/development/api_styleguide.md index 721353ca449ebd..cbee0c61dc39e1 100644 --- a/doc/development/api_styleguide.md +++ b/doc/development/api_styleguide.md @@ -93,6 +93,7 @@ While we commit to maintaining API stability, there are limited circumstances wh - Create a new issue to delete the `403 Forbidden` response and set the milestone. Example: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/190512 + ### What to do instead of a breaking change The following sections suggest alternatives to making breaking changes. -- GitLab From 7691b162513a0fb35ed9ebfe67ec3301e232d4e1 Mon Sep 17 00:00:00 2001 From: Bogdan Denkovych Date: Fri, 20 Jun 2025 12:20:26 +0300 Subject: [PATCH 5/8] Update, sentence that links to issue and merge requests as examples --- doc/development/api_styleguide.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/development/api_styleguide.md b/doc/development/api_styleguide.md index cbee0c61dc39e1..0adb4c8aa24013 100644 --- a/doc/development/api_styleguide.md +++ b/doc/development/api_styleguide.md @@ -92,8 +92,7 @@ While we commit to maintaining API stability, there are limited circumstances wh - Keep the `403 Forbidden` response with the message until the next major GitLab version is released. - Create a new issue to delete the `403 Forbidden` response and set the milestone. -Example: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/190512 - +For example, see [issue 424505](https://gitlab.com/gitlab-org/gitlab/-/issues/424505) and the [merge request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/190512). ### What to do instead of a breaking change The following sections suggest alternatives to making breaking changes. -- GitLab From b8f6a019b8fdb6ae441b1007c12ea5b2d63902c3 Mon Sep 17 00:00:00 2001 From: Bogdan Denkovych Date: Fri, 20 Jun 2025 12:22:57 +0300 Subject: [PATCH 6/8] Apply suggestion from GitLab Duo about the wording --- doc/development/api_styleguide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/development/api_styleguide.md b/doc/development/api_styleguide.md index 0adb4c8aa24013..32ec2b29075fe6 100644 --- a/doc/development/api_styleguide.md +++ b/doc/development/api_styleguide.md @@ -88,7 +88,7 @@ While we commit to maintaining API stability, there are limited circumstances wh 1. **Security fixes**: If a breaking change is necessary as part of a security fix, we may make the change to protect users and their data. In such cases, we will: - Document the change thoroughly in the API documentation. - Provide migration guidance for API consumers. - - Ensure the instead of removed behavior, API endpoint returns a `403 Forbidden` response with a message that provides a reason for the breaking change and points to the documentation. + - Ensure the API endpoint returns a `403 Forbidden` response with a message that provides a reason for the breaking change and points to the documentation, instead of the removed behavior. - Keep the `403 Forbidden` response with the message until the next major GitLab version is released. - Create a new issue to delete the `403 Forbidden` response and set the milestone. -- GitLab From e386f26c38338ba5be429a749b801fe38b8a4247 Mon Sep 17 00:00:00 2001 From: Bogdan Denkovych Date: Fri, 20 Jun 2025 12:24:00 +0300 Subject: [PATCH 7/8] Apply clarifications from GitLab Duo --- doc/development/api_styleguide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/development/api_styleguide.md b/doc/development/api_styleguide.md index 32ec2b29075fe6..fe40a109e8c284 100644 --- a/doc/development/api_styleguide.md +++ b/doc/development/api_styleguide.md @@ -92,7 +92,7 @@ While we commit to maintaining API stability, there are limited circumstances wh - Keep the `403 Forbidden` response with the message until the next major GitLab version is released. - Create a new issue to delete the `403 Forbidden` response and set the milestone. -For example, see [issue 424505](https://gitlab.com/gitlab-org/gitlab/-/issues/424505) and the [merge request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/190512). +For an example of implementing a security-related breaking change following these guidelines, see [issue 424505](https://gitlab.com/gitlab-org/gitlab/-/issues/424505) and the [merge request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/190512). ### What to do instead of a breaking change The following sections suggest alternatives to making breaking changes. -- GitLab From c93a05de8165c1e9a67757c95bf0879d79a90653 Mon Sep 17 00:00:00 2001 From: Bogdan Denkovych Date: Fri, 20 Jun 2025 12:36:49 +0300 Subject: [PATCH 8/8] Add empty line --- doc/development/api_styleguide.md | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/development/api_styleguide.md b/doc/development/api_styleguide.md index fe40a109e8c284..3fd43e94f4e002 100644 --- a/doc/development/api_styleguide.md +++ b/doc/development/api_styleguide.md @@ -93,6 +93,7 @@ While we commit to maintaining API stability, there are limited circumstances wh - Create a new issue to delete the `403 Forbidden` response and set the milestone. For an example of implementing a security-related breaking change following these guidelines, see [issue 424505](https://gitlab.com/gitlab-org/gitlab/-/issues/424505) and the [merge request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/190512). + ### What to do instead of a breaking change The following sections suggest alternatives to making breaking changes. -- GitLab