Merge branch 'ld-graphql-docs-feature-flag-field-value' into 'master'

Docs for using flags with GraphQL field values

See merge request gitlab-org/gitlab!28737

doc/development/api_graphql_styleguide.md

@@ -258,30 +258,78 @@ end
 
 ## Feature flags
 
-Features controlled by feature flags often provide GraphQL functionality. When a feature
-is enabled or disabled by a feature flag, the related GraphQL functionality should also
-be enabled or disabled.
+Developers can add [feature flags](../development/feature_flags/index.md) to GraphQL
+fields in the following ways:
 
-Fields can be put behind a feature flag so they can conditionally return the value for
-the field depending on if the feature has been enabled or not.
+- Add the `feature_flag` property to a field. This will allow the field to be _hidden_
+  from the GraphQL schema when the flag is disabled.
+- Toggle the return value when resolving the field.
 
-GraphQL feature flags use the common
-[GitLab feature flag](../development/feature_flags.md) system, and can be added to a
-field using the `feature_flag` property.
+You can refer to these guidelines to decide which approach to use:
 
-For example:
+- If your field is experimental, and its name or type is subject to
+  change, use the `feature_flag` property.
+- If your field is stable and its definition will not change, even after the flag is
+  removed, toggle the return value of the field instead. Note that
+  [all fields should be nullable](#nullable-fields) anyway.
+
+### `feature_flag` property
+
+The `feature_flag` property allows you to toggle the field's
+[visibility](https://graphql-ruby.org/authorization/visibility.html)
+within the GraphQL schema. This will remove the field from the schema
+when the flag is disabled.
+
+A description is [appended](https://gitlab.com/gitlab-org/gitlab/-/blob/497b556/app/graphql/types/base_field.rb#L44-53)
+to the field indicating that it is behind a feature flag.
+
+CAUTION: **Caution:**
+If a client queries for the field when the feature flag is disabled, the query will
+fail. Consider this when toggling the visibility of the feature on or off on
+production.
+
+The `feature_flag` property does not allow the use of
+[feature gates based on actors](../development/feature_flags/development.md).
+This means that the feature flag cannot be toggled only for particular
+projects, groups, or users, but instead can only be toggled globally for
+everyone.
+
+Example:
 
 ```ruby
 field :test_field, type: GraphQL::STRING_TYPE,
       null: true,
       description: 'Some test field',
-      feature_flag: :some_feature_flag
+      feature_flag: :my_feature_flag
 ```
 
-In the above example, the `test_field` field will only be returned if
-the `some_feature_flag` feature flag is enabled.
+### Toggle the value of a field
+
+This method of using feature flags for fields is to toggle the
+return value of the field. This can be done in the resolver, in the
+type, or even in a model method, depending on your preference and
+situation.
 
-If the feature flag is not enabled, an error will be returned saying the field does not exist.
+When applying a feature flag to toggle the value of a field, the
+`description` of the field must:
+
+- State that the value of the field can be toggled by a feature flag.
+- Name the feature flag.
+- State what the field will return when the feature flag is disabled (or
+  enabled, if more appropriate).
+
+Example:
+
+```ruby
+field :foo, GraphQL::STRING_TYPE,
+      null: true,
+      description: 'Some test field. Will always return `null`' \
+                   'if `my_feature_flag` feature flag is disabled'
+
+def foo
+  object.foo unless Feature.enabled?(:my_feature_flag, object)
+end
+```
 
 ## Deprecating fields