Commit d6aff9ca authored by Evan Read's avatar Evan Read

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
parents a600d3f5 1b71c5e5
......@@ -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
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment