Improve documentation on developing with feature flags
https://docs.gitlab.com/ee/development/feature_flags.html has a couple of issues:
- It contradicts https://docs.gitlab.com/ee/development/rolling_out_changes_using_feature_flags.html and https://gitlab.com/gitlab-org/gitlab-ce/blob/master/PROCESS.md#feature-flags on whether feature flags should be on or off by default. This is further discussed in https://gitlab.com/gitlab-org/gitlab-ce/issues/59705
- It talks about feature groups that can be defined in
Feature#register_feature_groups
, which is an empty method, with no further information on when to use or how to implement one - The "Developing with feature flags" section contains instructions on how to prepare a model for being used as a feature flag actor (like a group, project, or user) which is not relevant to most people who simply want to use feature flags with the existing actors (group, project, user)
- It contains some notes on enabling flags using chatops, which is more appropriate for https://docs.gitlab.com/ee/development/rolling_out_changes_using_feature_flags.html
- It says "For GitLab.com, team members have access to feature flags through chatops." which is incorrect; people don't have access automatically, and it's not documented how to gain access
- It says "Only percentage gates are supported at this time." which is incorrect, as feature group and actor based gates are also supported
- It's unclear what can be passed to
Feature.enabled?
as an actor; the text says "it’s better to have a group- or user-based gate" but the code code example usesproject
- It's unclear that if you provide a group, project or user as as an actor to
Feature.enabled?
, you can then only use--group
or--project
or--user
when enabling it depending on what was passed, and the feature flag will only be on if the providedthing
matches exactly with the provided group/project/user path. We say it's bad to not pass an actor, but what actor do we recommend when and why? - It says using actors "allows for enabling for the
gitlab-org
group first, while the rest of the users aren’t impacted", which is incorrect. If the check looks likeFeature.enabled?(:flag, group)
, enabling a feature with--group=gitlab-org
would enable the feature on thegitlab-org
group for all users, not on all groups for users that are members of thegitlab-org
group. To enable a feature only for specific users, we would need to passcurrent_user
as an actor toFeature.enabled?
and then use chatops to individually enable the feature for these people. There is not currently a way to enable a feature only for users that are members of a specific group. - It's unclear that the call to
push_frontend_feature_flag
needs to use the same actor anddefault_enabled
that are provided toFeature.enabled?
calls
https://docs.gitlab.com/ee/api/features.html#set-or-create-a-feature does too:
- It says "Note that you can enable or disable a feature for a feature_group, a user, a group, and a project in a single API call.", which is confusing, since a feature flag will actually only support the type that is passed as an actor to its
Feature.enabled?
checks
As does https://docs.gitlab.com/ee/development/rolling_out_changes_using_feature_flags.html:
- It says "Feature gates can also be actor based, for example a feature could first be enabled for only the gitlab-ce project. The project is passed by supplying a --project flag:" but doesn't specify that this will only work if a project was passed as an actor to the
Feature.enabled?
check