Allow breaking changes in REST API due to critical security or performance concerns
This issue was created from this comment https://gitlab.com/gitlab-org/manage/manage-workspace/discussions/-/issues/40#note_1097996412.
This change should go through the broader changes process.
Problem
There are likely times when a critical security or performance problem is a reason to make a breaking change to our REST or GraphQL API outside of the breaking change rules.
In our GraphQL client docs we have a caveat (added in !55328 (merged)):
GitLab makes all attempts to follow the deprecation and removal process. On rare occasions, GitLab might make immediate breaking changes to the GraphQL API to patch critical security or performance concerns if the deprecation process would pose significant risk.
But we lack any concrete guidelines around this. Formalising the rules will give customers and developers some certainty over what is allowed and not allowed.
Proposal
Form rules based on the severity of the problem (S-label).
Document this clearly for both customers and developers, in both our REST and GraphQL API docs.
We should still advise developers that if possible the change should be a "soft" breaking change, for example, returning a null
or empty array in place of data rather than removing a field.
Need to define: what threshold of severity allows use to make a breaking change?
This hasn't been discussed widely yet.
This is based on severity levels of the bugperformance or security issue.
-
severity1
- Can be made on any milestone.
- Strongly recommended to explore other options
😅 . - If "soft"-breaking, a deprecation file created.
- If breaking, a removal file should be created.
-
severity2
- Can be made only on major milestones.
- Deprecation file should be created immediately so change is announced.
-
Open questions - Please provide feedback!
- If it is early in the major milestone (like
15.1
) is it realistic and fair to wait ~a year and release the breaking change in16.0
? - Should we enforce the normal 3-month deprecation period before the breaking change, in which case if it is very late in the major milestone (like
14.11
) we would wait longer than a year and release the breaking change in16.0
? - Would it be better to allow this kind of breaking change to happen on either the
M.0
orM.6
milestones, with at least a 3-month deprecation notice period?
- If it is early in the major milestone (like
-
severity3 severity4
- Must follow the API breaking change guidelines. GraphQL: deprecation + breaking change according to our schedule. REST: No breaking change is allowed.