Clarify documentation about feature-flagged GraphQL entities

We currently provide some hints on how to deal with feature flags in GraphQL queries but it has some flaws:

  • We recommend using the @include directive, but we do not clearly state that this requires feature-flagged entities to exist in the schema, no matter what the directive evaluates to. So, in the case where the flag is off, we should recommend that the corresponding resolver returns null in the backend.
    • We could also mention the @skip directive which is the opposite of @include and can be used for similar purposes.
  • It might be worth mentioning that another option to dealing with this is to maintain 2 versions of a client-side query: one including the new fields, and the other one without them. Then, the client should trigger the correct query based on the feature flag's state. This is a less maintainable approach as it involves duplicated code, but it can be useful in cases where the field is removed from the schema when the flag is off.

/cc @farias-gl