Merging of @deprecated directives

[tobias-tengler]

The merging of @deprecated directives feels to me like a different concern from merging user-defined type system directives, so I'm opening this issue to discuss possible approaches.

IMO a field in the composite schema should only be marked as @deprecated if it has been marked as such in each source schema.

Therefore I'd propose to update MergeOutputFields, MergeInputFields, MergeArguments and MergeEnumValues to something like this:

- Let {firstField} be the first field in {fields}.
...
- Let {fieldDeprecationReason} be the deprecation reason of {firstField}.
- For each {field} in {fields}:
  ...
  - Let {deprecationReason} be the deprecation reason of {field}.
  - If {deprecationReason} is {null}:
    - Let {fieldDeprecationReason} be null

My reasoning behind this change is that if a team marks a field as @deprecated in their schema, it either ends up as @deprecated in the composite schema right away, or if not, it's a signal that they have to talk to the other team(s) contributing that field.
In that case they can decide with the other team(s) to also mark their version of the field as @deprecated for a user-facing phase-out, or if the field should just be phased out from their schema, the other team(s) can utilize @override to steer the traffic away from their source schema.

[glen-84]

I'm just wondering, why should @deprecated be merged via the properties and not simply as a directive?

We'll be merging other things like @tag, which are not available as properties (as far as I know).

It may also make the composition more configurable. Assuming a directives-on-directives approach (not yet supported by the GraphQL spec, but just as an example):

directive @deprecated(
  reason: String! = "No longer supported"
) on FIELD_DEFINITION | ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION | ENUM_VALUE
    @compose(mergeBehavior: "...")
    @inaccessible

You could potentially do something like the above to control the merge behavior, make the directive inaccessible, etc., and then it would be as configurable as any other directive in the source schema.

[tobias-tengler]

I chose to handle @deprecated as a separate property of the type system member, since the GraphQL specification and introspection types do the same thing.
Depending on how directive merging will work, the @deprecated directive can definitely be merged as just any other directive though.

After talking with @michaelstaib I did not implement the @deprecated merging behavior I described above, but a simpler version, where the composite type system member is marked as @deprecated if any source schema for that member has the @deprecated directive. For the reason I'm taking the first non-null instance of that argument from the set of source schema @deprecated directives.

I'd still be interested to know how large corporations approach the process of deprecation and if they would prefer a more coordinated approach as I described above or not.