Merge branch 'docs-feature-flag-update' into 'master'

Clarify feature flag docs

See merge request gitlab-org/gitlab!34711

doc/api/feature_flags.md

@@ -9,7 +9,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9566) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.5.
 
 NOTE: **Note**
-This API is behind a [feature flag](../user/project/operations/feature_flags.md#feature-flag-behavior-change-in-130). If this flag is not enabled in your environment, you can use the [legacy feature flags API](feature_flags_legacy.md).
+This API is behind a [feature flag](../user/project/operations/feature_flags.md#enable-or-disable-feature-flag-strategies).
+If this flag is not enabled in your environment, you can use the [legacy feature flags API](feature_flags_legacy.md).
 
 API for accessing resources of [GitLab Feature Flags](../user/project/operations/feature_flags.md).
 

doc/user/project/operations/feature_flags.md

@@ -35,125 +35,147 @@ To create and enable a feature flag:
 
 1. Navigate to your project's **Operations > Feature Flags**.
 1. Click the **New feature flag** button.
-1. Enter a name that starts with a letter and contains only lowercase letters, digits, underscores (`_`)
-   and dashes (`-`), and does not end with a dash (`-`) or underscore (`_`).
-1. Enter a description (optional, 255 characters max).
-1. Enter details about how the flag should be applied:
-   - In GitLab 13.0 and earlier: Enter an environment spec,
-     enable or disable the flag in this environment, and select a rollout strategy.
-   - In GitLab 13.1 and later (when [this feature flag](#feature-flag-behavior-change-in-130) is enabled): Select a strategy and then
-     the environments to apply the strategy to.
+1. Fill in the details:
+   - Enter a name that starts with a letter and contains only lowercase letters, digits, underscores (`_`),
+     or dashes (`-`), and does not end with a dash (`-`) or underscore (`_`).
+   - Enter a description (optional, 255 characters max).
+   - In GitLab 13.0 and earlier, add **Environment specs**. For each environment,
+     include the:
+     - Status (default enabled)
+     - [Rollout strategy](#rollout-strategy-legacy) (defaults to all users)
+   - In GitLab 13.1 and later, add Feature Flag [**Strategies**](#feature-flag-strategies). For
+     each strategy, include the:
+     - Type (defaults to [All users](#all-users))
+     - Environment (defaults to all environments)
 1. Click **Create feature flag**.
 
-The feature flag is displayed in the list. It is enabled by default.
+You can change these settings by clicking the **{pencil}** (edit) button
+next to any feature flag in the list.
 
-## Disable a feature flag for a specific environment
-
-In [GitLab 13.0 and earlier](https://gitlab.com/gitlab-org/gitlab/-/issues/8621),
-to disable a feature flag for a specific environment:
-
-1. Navigate to your project's **Operations > Feature Flags**.
-1. For the feature flag you want to disable, click the Pencil icon.
-1. To disable the flag:
-   - In GitLab 13.0 and earlier: Slide the Status toggle for the environment. Or, to delete the
-     environment spec, on the right, click the **Remove (X)** icon.
-   - In GitLab 13.1 and later (when [this feature flag](#feature-flag-behavior-change-in-130) is
-     enabled): For each strategy it applies to, under **Environments**, delete the environment.
-1. Click **Save changes**.
-
-## Disable a feature flag for all environments
-
-To disable a feature flag for all environments:
-
-1. Navigate to your project's **Operations > Feature Flags**.
-1. For the feature flag you want to disable, slide the Status toggle to **Disabled**.
-
-The feature flag is displayed on the **Disabled** tab.
+## Rollout strategy (legacy)
 
-## Feature flag behavior change in 13.0
-
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35555) in GitLab 13.0.
-
-Starting in GitLab 13.0, you can apply a feature flag strategy across multiple environments,
-without defining the strategy multiple times.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8240) in GitLab 12.2.
 
-This feature is under development and not ready for production use. It is
-deployed behind a feature flag that is **disabled by default**.
-[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md)
-can enable it for your instance.
+In GitLab 13.0 and earlier, the **Rollout strategy** setting affects which users will experience
+the feature as enabled. Choose the percentage of users that the feature will be enabled
+for. The rollout strategy will have no effect if the environment spec is disabled.
 
-To enable it:
+It can be set to:
 
-```ruby
-Feature.enable(:feature_flags_new_version)
-```
-
-To disable it:
-
-```ruby
-Feature.disable(:feature_flags_new_version)
-```
+- All users
+- [Percent rollout (logged in users)](#percent-rollout-logged-in-users)
+  - Optionally, you can click the **Include additional user IDs** checkbox and add a list
+    of specific users IDs to enable the feature for.
+- [User IDs](#user-ids)
 
 ## Feature flag strategies
 
-GitLab Feature Flag uses [Unleash](https://unleash.github.io)
-as the feature flag engine. In Unleash, there is a concept of rulesets for granular feature flag controls,
-called [strategies](https://unleash.github.io/docs/activation_strategy).
-Supported strategies for GitLab Feature Flags are described below.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35555) in GitLab 13.0.
+> - It's deployed behind a feature flag, disabled by default.
+> - It's enabled on GitLab.com.
+> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-feature-flag-strategies). **(CORE ONLY)**
 
-### Rollout strategy
+You can apply a feature flag strategy across multiple environments, without defining
+the strategy multiple times.
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8240) in GitLab 12.2.
+GitLab Feature Flags use [Unleash](https://unleash.github.io) as the feature flag
+engine. In Unleash, there are [strategies](https://unleash.github.io/docs/activation_strategy)
+for granular feature flag controls. GitLab Feature Flags can have multiple strategies,
+and the supported strategies are:
 
-The selected rollout strategy affects which users will experience the feature as enabled.
+- [All users](#all-users)
+- [Percent rollout (logged in users)](#percent-rollout-logged-in-users)
+- [User IDs](#user-ids)
+- [List](#list)
 
-The status of an environment spec ultimately determines whether or not a feature is enabled at all.
-For instance, a feature will always be disabled for every user if the matching environment spec has a disabled status, regardless of the chosen rollout strategy.
-However, a feature will be enabled for 50% of logged-in users if the matching environment spec has an enabled status along with a **Percent rollout (logged in users)** strategy set to 50%.
+Strategies can be added to feature flags when [creating a feature flag](#create-a-feature-flag),
+or by editing an existing feature flag after creation by navigating to **Operations > Feature Flags**
+and clicking **{pencil}** (edit).
 
-#### All users
+### All users
 
-Enables the feature for all users. It is implemented using the Unleash
-[`default`](https://unleash.github.io/docs/activation_strategy#default)
-activation strategy.
+Enables the feature for all users. It uses the [`default`](https://unleash.github.io/docs/activation_strategy#default)
+Unleash activation strategy.
 
-#### Percent rollout (logged in users)
+### Percent rollout (logged in users)
 
-Enables the feature for a percentage of authenticated users. It is
-implemented using the Unleash
+Enables the feature for a percentage of authenticated users. It uses the
 [`gradualRolloutUserId`](https://unleash.github.io/docs/activation_strategy#gradualrolloutuserid)
-activation strategy.
+Unleash activation strategy.
 
-Set a value of 15%, for example, to enable the feature for 15% of authenticated users.
+For example, set a value of 15% to enable the feature for 15% of authenticated users.
 
-A rollout percentage may be between 0% and 100%.
+The rollout percentage can be from 0% to 100%.
 
 CAUTION: **Caution:**
 If this strategy is selected, then the Unleash client **must** be given a user
 ID for the feature to be enabled. See the [Ruby example](#ruby-application-example) below.
 
-#### User IDs
+### User IDs
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8240) in GitLab 12.2. [Updated](https://gitlab.com/gitlab-org/gitlab/-/issues/34363) to be defined per environment in GitLab 12.6.
 
-A feature flag may be enabled for a list of target users. It is implemented
+Enables the feature for a list of target users. It is implemented
 using the Unleash [`userWithId`](https://unleash.github.io/docs/activation_strategy#userwithid)
 activation strategy.
 
-User IDs should be a comma-separated list of values. For example, `user@example.com, user2@example.com`, or `username1,username2,username3`, etc.
+Enter user IDs as a comma-separated list of values. For example,
+`user@example.com, user2@example.com`, or `username1,username2,username3`, and so on.
 
 CAUTION: **Caution:**
 The Unleash client **must** be given a user ID for the feature to be enabled for
 target users. See the [Ruby example](#ruby-application-example) below.
 
-#### List
+### List
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35930) in GitLab 13.1.
 
-A feature flag can be enabled for lists of users created with the [Feature Flag User List API](../../../api/feature_flag_user_lists.md).
+Enables the feature for lists of users created with the [Feature Flag User List API](../../../api/feature_flag_user_lists.md).
 Similar to [User IDs](#user-ids), it uses the Unleash [`userWithId`](https://unleash.github.io/docs/activation_strategy#userwithid)
 activation strategy.
 
+### Enable or disable feature flag strategies
+
+This feature is under development, but is ready for testing. It's
+deployed behind a feature flag that is **disabled by default**.
+[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md)
+can enable it for your instance.
+
+To enable it:
+
+```ruby
+Feature.enable(:feature_flags_new_version)
+```
+
+To disable it:
+
+```ruby
+Feature.disable(:feature_flags_new_version)
+```
+
+## Disable a feature flag for a specific environment
+
+In [GitLab 13.0 and earlier](https://gitlab.com/gitlab-org/gitlab/-/issues/8621),
+to disable a feature flag for a specific environment:
+
+1. Navigate to your project's **Operations > Feature Flags**.
+1. For the feature flag you want to disable, click the Pencil icon.
+1. To disable the flag:
+   - In GitLab 13.0 and earlier: Slide the Status toggle for the environment. Or, to delete the
+     environment spec, on the right, click the **Remove (X)** icon.
+   - In GitLab 13.1 and later: For each strategy it applies to, under **Environments**, delete the environment.
+
+1. Click **Save changes**.
+
+## Disable a feature flag for all environments
+
+To disable a feature flag for all environments:
+
+1. Navigate to your project's **Operations > Feature Flags**.
+1. For the feature flag you want to disable, slide the Status toggle to **Disabled**.
+
+The feature flag is displayed on the **Disabled** tab.
+
 ## Integrate feature flags with your application
 
 To use feature flags with your application, get access credentials from GitLab.