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 uses project
  • 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 provided thing 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 like Feature.enabled?(:flag, group), enabling a feature with --group=gitlab-org would enable the feature on the gitlab-org group for all users, not on all groups for users that are members of the gitlab-org group. To enable a feature only for specific users, we would need to pass current_user as an actor to Feature.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 and default_enabled that are provided to Feature.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