Merge branch 'nullable-graphql-fields' into 'master'

GraphQL fields should generally be nullable

See merge request gitlab-org/gitlab!26001

doc/development/api_graphql_styleguide.md

@@ -76,6 +76,28 @@ a new presenter specifically for GraphQL.
 The presenter is initialized using the object resolved by a field, and
 the context.
 
+### Nullable fields
+
+GraphQL allows fields to be be "nullable" or "non-nullable". The former means
+that `null` may be returned instead of a value of the specified type. **In
+general**, you should prefer using nullable fields to non-nullable ones, for
+the following reasons:
+
+- It's common for data to switch from required to not-required, and back again
+- Even when there is no prospect of a field becoming optional, it may not be **available** at query time
+  - For instance, the `content` of a blob may need to be looked up from Gitaly
+  - If the `content` is nullable, we can return a **partial** response, instead of failing the whole query
+- Changing from a non-nullable field to a nullable field is difficult with a versionless schema
+
+Non-nullable fields should only be used when a field is required, very unlikely
+to become optional in the future, and very easy to calculate. An example would
+be `id` fields.
+
+Further reading:
+
+- [GraphQL Best Practices Guide](https://graphql.org/learn/best-practices/#nullability)
+- [Using nullability in GraphQL](https://blog.apollographql.com/using-nullability-in-graphql-2254f84c4ed7)
+
 ### Exposing Global IDs
 
 When exposing an `ID` field on a type, we will by default try to