Discussion: How should GitLab handle breaking schema changes in its GraphQL API?
Problem
The golden standard of a GraphQL API is not to version (or need to version) your API, but there are some cases where breaking changes may need to be made. One example is removing (backwards-compatible) deprecated parts of the schema.
GitLab currently can not deliver breaking changes to its GraphQL API without breaking integrations without warning.
Solution proposals
1. Announce breaking changes ahead of time
Github announce up-coming breaking changes and have a predictable schedule for their release https://developer.github.com/v4/breaking_changes
We'll announce upcoming breaking changes at least three months before making changes to the GraphQL schema, to give integrators time to make the necessary adjustments. Changes go into effect on the first day of a quarter (January 1st, April 1st, July 1st, or October 1st). For example, if we announce a change on January 15th, it will be made on July 1st.
2. Version the API
GraphQL APIs that are being versioned:
- Shopify https://help.shopify.com/en/api/graphql-admin-api/graphiql-explorer (using
{YYYY}-{MM}) - Yelp https://www.yelp.com/developers/graphql/guides/intro (using
v{n})
Tracking conversation
-
💪 consensus strong -
🔶 consensus seems to be reached through compromise by some -
⌛ still being discussed
| proposal | consensus | threads |
|---|---|---|
| Breaking changes can be made after a set period of deprecation | #32292 (comment 221035619) | |
Announce n releases in advance |
#32292 (comment 223253275) gitlab-com/Product#507 (closed) | |
| We track deprecations in milestoned issues | mentioned once in #32292 (comment 223227734) | |
deprecation_reason mentions removal milestone, links to the deprecation issue, backed up by a cop |
#32292 (comment 222813225) #32292 (comment 223227734) | |
| Pushing announcements | #32292 (comment 224730760) | |
| Something missing? Add it! |
Docs changes for development/api_graphql_styleguide
(https://docs.gitlab.com/ee/api/graphql/index.html))
- How to deprecate when a value is changed #32292 (comment 221035619)
- Any rules we decide around
deprecation_reason - Where to publish the change (i.e., add it to a particular issue, update [api/graphql]
Docs changes for api/graphql
- What our deprecation schedule is
- List of planned future breaking changes and milestones, or a link to them
- (Potentially) how to stay informed