Encourage GraphQL deprecations to be kept around indefinitely where possible

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

• Work on this issue
• Close this issue

This issue is part of the Epic &7155 (closed). Please see that Epic for more context.

About

Currently, we allow deprecated GraphQL schema to be removed on major milestones #345970 (closed).

With %15.0 only 3 milestones away GitLab is planning to introduce breaking changes as deprecated schema is removed.

Problem

A lot of deprecated schema would be trivial for GitLab to support for longer.

As @alexkalderimis stated #334278 (comment 735090977):

For some things, especially where there is a performance penalty or other implication, removal is the correct approach, but for GraphQL, where fields don't have to be requested, I just don't see the benefit of removing old terminology, or even leaving it marked as deprecated permanently.

So one thing I'd like to advocate for is greater backwards compatibility, especially where it costs us so little.

GitLab also arguably could do more to alert consumers of their use of deprecated schema (#341095, #353008).

Proposal

We continue to deprecate items as normal and continue to encourage consumers to not use them, and continue to advise consumers of the deprecation removal cycle.

We change our internal process to support old schema where possible.

We provide guidance for developers on how to go about this:

• Remove schema that has performance cost on normal deprecation/removal cycles.
• Continue to adapt deprecated schema within GraphQL classes where possible beyond the removal milestone (ideally, indefinitely): alias fields or enums to new values, rename arguments inside resolving methods.
• If adapting in GraphQL long-term is not feasible (perhaps due to impact outside of GraphQL classes), on the removal milestone, make the items do nothing: fields return null, ignore arguments. The schema item's description should be updated to state that it does nothing.

As part of the backfilling mentioned in #345974 (comment 849203497) we can encourage developers to postpone the removal when creating Deprecation issues.

Cruft

In the long term we could address the problem of “cruft” in the GraphQL codebase with a tidy solution of placing support for deprecated schema elsewhere (perhaps something inspired somewhat by graphql-ruby’s changesets, although likely simpler).