Skip to content

Allow breaking changes to GraphQL API on twice-yearly schedule

I would like us to make a change to our Maintenance Policy to allow breaking changes in our GraphQL in the .6 release as well as the .0 release. Any breaking changes we announce would take a minimum of six months to take effect:

  1. Any breaking changes announced by the .0 release in May can take effect in the .6 release in November.
  2. Any breaking changes announced by the .6 release in November can take effect in the .0 release in May.

As a result, if a breaking change is announced in, say, the .1 release in June, it needs to wait until the next .0 release to take effect because the .6 release is less than six months away.

(This is no longer strict semantic versioning, but it's questionable whether strict semantic versioning is even possible for security fixes with our current versioning policy.)

Background

In #50 (closed), we set a yearly major release schedule for GitLab. In May 2020, we'll release GitLab 13.0. In May 2021, we'll release GitLab 14.0.

Our Maintenance Policy says:

GitLab uses Semantic Versioning for its releases: (Major).(Minor).(Patch).

That means that breaking changes to the API can only appear in the annual major release. For the REST API, this is broadly fine as it's quite slow-moving. For GraphQL, we might want to consider an exemption to this. (We had some discussion among engineering about this in gitlab-org/gitlab#32292 (closed), but @marin pointed out that this is the responsibility of the Product team.)

Quoting @.luke from gitlab-org/gitlab#32292 (closed):

The golden standard with GraphQL is not to version (or need to version) your API, but there are some cases where breaking changes may need to be made. These include:

GitLab currently can not deliver breaking changes to its GraphQL API without unfairly breaking integrations without warning.

We can do this with annual releases, but we need to be careful because we also need a warning period. For instance, if we announced a deprecation in release X.11 and made it happen in Y.0, that would only give people a month to react. So we need a cadence that defines a minimum supported period for upcoming deprecations.

If we couple this to the major version release and use a year for this, then that means that the longest time possible for a breaking change to happen is 23 months - announce in X.1, enforce in Z.0. In GitLab years, that's a very long time.

Among backend engineers, a minimum supported period of six months seemed the happiest compromise: it gives integrators time to adapt, without us having to snap to a yearly cadence. It's also longer than GitHub's policy (again, quoting from @.luke):

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.