Allow deprecating types

[stubailo]

The last discussion of this is #197 (comment)

For purposes of tooling and documentation, it would be nice to be able to deprecate an entire type. This is useful for cases where you're trying to transition to a new object type, and you would like to prevent people from adding new fields which reference the old type.

[mannyistyping]

I am definitely interested and curious on the communities thoughts around this proposal.

Some coworkers were wanting to remove a type completely and transition to a new object type.
We ended up deprecating the Queries that were returning the "out dated" type.

I can see value in marking a type as "out dated" and providing deprecation reason to instead use a newer type that is meant to replace.

[gwardwell]

Deprecating the type lends clarity to the intent of the schema change. If the queries/mutations/fields that return the type are deprecated, that doesn’t indicate that no new queries/mutations/fields returning the type should be created. In that sense, it doesn’t communicate that it’s not the schema returning the type that is the problem, but the type itself.

Ultimately the queries/mutations/fields and type should be deprecated. That creates clear communication that the type is being retired as well as all the corresponding schema returning it.

Additionally, since types can appear in query documents by way of fragments, it makes sense for type deprecation to be communicated to client applications that may be referencing them.

[benjie]

@fotoetienne is championing @deprecated on object types via #997