Form a process for ensuring alpha API schema is made GA
Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.
Note, see https://docs.gitlab.com/ee/policy/alpha-beta-support.html for definitions of alpha and GA.
About
Our GraphQL API allows us to mark new schema items as alpha. This allows the schema item to be changed without needing to go through deprecation cycles, so is good for when we are developing a new feature.
Problem
We do not have a process for ensuring that a schema item marked as alpha is later released as GA when the feature is stable. Our frontend can consume alpha items happily when they are alpha, so without a process, by default alpha items are unlikely to be released to the public.
When a GraphQL schema item is marked as alpha, we leverage the native GraphQL @deprecated schema directive in order to discourage its use. This can mean that GraphQL tooling hides the alpha field, or warns of its usage. For example, the GraphiQL (see our mounted version of GraphiQL) autocomplete editor doesn’t suggest deprecated fields.
So schema marked as alpha in our GraphQL API means the item is reasonably hidden from the public use of tooling and remains hidden unless released as GA.
Releasing alpha schema as GA encourages external integration with those features. The public can build on alpha features, but are discouraged from doing this. We want to encourage integration with our API and our features. We also want to keep alpha meaningful, so external developers continue to not integrate with alpha schema, rather than for it to be interpreted as potentially stable but maybe just forgotten about by GitLab.
Proposal
Please discuss!
Some quick thoughts:
Documentation
Update our GraphQL developer docs to explain the reasons for moving schema items from alpha to GA (see Problem).
Release issue
We already require alpha items to provide a milestone of when the item was introduced. We can add a new required argument related to tracking its GA release in an issue.
field :foo, alpha: { milestone: '16.1', issue_url: 'https://...' }Expected release timeframe
Note: See #412764 (comment 1404300153) for a good argument why not to do this.
We already require alpha items to provide a milestone of when the item was introduced. We could add a new required argument to state when we expect (but not require) an alpha field to be GA. This milestone would not be published in our generated API docs.
field :foo, alpha: { milestone: '16.1', expected_release: '16.4' }If the item is still alpha beyond that milestone, we would expect a team to either:
- Update the
expected_release:if the item is still alpha. - Release the item as GA.
I'm unsure how we would periodically check these expired alpha fields, but perhaps we could periodically generate an issue with items past their expected release and ping teams to assess them.
Combo
Or, why not both?
field :foo, alpha: { milestone: '16.1', expected_release: '16.4', issue_url: 'https://...' } }