diff --git a/doc/development/api_styleguide.md b/doc/development/api_styleguide.md index b895ec0e1b1a746f301a4b2be56eddf56d5789cb..3fd43e94f4e0022aa2d649cfd6460047be3c1431 100644 --- a/doc/development/api_styleguide.md +++ b/doc/development/api_styleguide.md @@ -81,6 +81,19 @@ 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. + - 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. + +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.