Add latest changes from gitlab-org/gitlab@13-1-stable-ee

2 files changed, 86 insertions, 13 deletions

diff --git a/doc/development/feature_flags/controls.md b/doc/development/feature_flags/controls.md
index 309aecd7978..d4d1ec74591 100644
--- a/doc/development/feature_flags/controls.md
+++ b/doc/development/feature_flags/controls.md
@@ -96,7 +96,7 @@ As a guideline:
 Before toggling any feature flag, check that there are no ongoing
 significant incidents on GitLab.com. You can do this by checking the
 `#production` and `#incident-management` Slack channels, or looking for
-[open incident issues](https://gitlab.com/gitlab-com/gl-infra/production/issues/?scope=all&utf8=%E2%9C%93&state=opened&label_name[]=incident)
+[open incident issues](https://gitlab.com/gitlab-com/gl-infra/production/-/issues/?scope=all&utf8=%E2%9C%93&state=opened&label_name[]=incident)
 (although check the dates and times).
 
 We do not want to introduce changes during an incident, as it can make
@@ -113,17 +113,58 @@ When you begin to enable the feature, please link to the relevant
 Feature Flag Rollout Issue within a Slack thread of the first `/chatops`
 command you make so people can understand the change if they need to.
 
-To enable a feature for 25% of all users, run the following in Slack:
+To enable a feature for 25% of the time, run the following in Slack:
 
 ```shell
 /chatops run feature set new_navigation_bar 25
 ```
 
+This sets a feature flag to `true` based on the following formula:
+
+```ruby
+feature_flag_state = rand < (25 / 100.0)
+```
+
 This will enable the feature for GitLab.com, with `new_navigation_bar` being the
 name of the feature.
 This command does *not* enable the feature for 25% of the total users.
 Instead, when the feature is checked with `enabled?`, it will return `true` 25% of the time.
 
+To enable a feature for 25% of actors such as users, projects, or groups,
+run the following in Slack:
+
+```shell
+/chatops run feature set some_feature 25 --actors
+```
+
+This sets a feature flag to `true` based on the following formula:
+
+```ruby
+feature_flag_state = Zlib.crc32("some_feature<Actor>:#{actor.id}") % (100 * 1_000) < 25 * 1_000]
+# where <Actor>: is a `User`, `Group`, `Project` and actor is an instance
+```
+
+During development, based on the nature of the feature, an actor choice
+should be made.
+
+For user focused features:
+
+```ruby
+Feature.enabled?(:feature_cool_avatars, current_user)
+```
+
+For group or namespace level features:
+
+```ruby
+Feature.enabled?(:feature_cooler_groups, group)
+```
+
+For project level features:
+
+```ruby
+Feature.enabled?(:feature_ice_cold_projects, project)
+```
+
 If you are not certain what percentages to use, simply use the following steps:
 
 1. 25%
@@ -158,15 +199,21 @@ you run these 2 commands:
 
 ```shell
 /chatops run feature set --project=gitlab-org/gitlab some_feature true
-/chatops run feature set some_feature 25
+/chatops run feature set some_feature 25 --actors
+```
+
+Then `some_feature` will be enabled for both 25% of actors and always when interacting with
+`gitlab-org/gitlab`. This is a good idea if the feature flag development makes use of group
+actors.
+
+```ruby
+Feature.enabled?(:some_feature, group)
 ```
 
-Then `some_feature` will be enabled for both 25% of users and all users interacting with
-`gitlab-org/gitlab`.
+NOTE:
 
-NOTE: **Note:**
 **Percentage of time** rollout is not a good idea if what you want is to make sure a feature
-is always on or off to the users.
+is always on or off to the users. In that case, **Percentage of actors** rollout is a better method.
 
 ### Feature flag change logging
 
@@ -174,7 +221,7 @@ Any feature flag change that affects GitLab.com (production) will
 automatically be logged in an issue.
 
 The issue is created in the
-[gl-infra/feature-flag-log](https://gitlab.com/gitlab-com/gl-infra/feature-flag-log/issues?scope=all&utf8=%E2%9C%93&state=closed)
+[gl-infra/feature-flag-log](https://gitlab.com/gitlab-com/gl-infra/feature-flag-log/-/issues?scope=all&utf8=%E2%9C%93&state=closed)
 project, and it will at minimum log the Slack handle of person enabling
 a feature flag, the time, and the name of the flag being changed.
 
diff --git a/doc/development/feature_flags/development.md b/doc/development/feature_flags/development.md
index b20db295919..a44bc70439e 100644
--- a/doc/development/feature_flags/development.md
+++ b/doc/development/feature_flags/development.md
@@ -23,6 +23,9 @@ class Foo < ActiveRecord::Base
 end
 ```
 
+Only models that `include FeatureGate` or expose `flipper_id` method can be
+used as an actor for `Feature.enabled?`.
+
 Features that are developed and are intended to be merged behind a feature flag
 should not include a changelog entry. The entry should either be added in the merge
 request removing the feature flag or the merge request where the default value of
@@ -87,6 +90,10 @@ this method you can expose the state of a feature flag as follows:
 
 ```ruby
 before_action do
+  # Prefer to scope it per project or user e.g.
+  push_frontend_feature_flag(:vim_bindings, project)
+
+  # Avoid, if possible
   push_frontend_feature_flag(:vim_bindings)
 end
 
@@ -115,17 +122,30 @@ how to access feature flags in a Vue component.
 
 ### Specs
 
-In the test environment `Feature.enabled?` is stubbed to always respond to `true`,
-so we make sure behavior under feature flag doesn't go untested in some non-specific
-contexts.
+Our Flipper engine in the test environment works in a memory mode `Flipper::Adapters::Memory`.
+`production` and `development` modes use `Flipper::Adapters::ActiveRecord`.
+
+### `stub_feature_flags: true` (default and preferred)
 
-Whenever a feature flag is present, make sure to test _both_ states of the
-feature flag.
+In this mode Flipper is configured to use `Flipper::Adapters::Memory` and mark all feature
+flags to be on-by-default and persisted on a first use. This overwrites the `default_enabled:`
+of `Feature.enabled?` and `Feature.disabled?` returning always `true` unless feature flag
+is persisted.
+
+Make sure behavior under feature flag doesn't go untested in some non-specific contexts.
 
 See the
 [testing guide](../testing_guide/best_practices.md#feature-flags-in-tests)
 for information and examples on how to stub feature flags in tests.
 
+### `stub_feature_flags: false`
+
+This disables a memory-stubbed flipper, and uses `Flipper::Adapters::ActiveRecord`
+a mode that is used by `production` and `development`.
+
+You should use this mode only when you really want to tests aspects of Flipper
+with how it interacts with `ActiveRecord`.
+
 ### Enabling a feature flag (in development)
 
 In the rails console (`rails c`), enter the following command to enable your feature flag
@@ -139,3 +159,9 @@ Similarly, the following command will disable a feature flag:
 ```ruby
 Feature.disable(:feature_flag_name)
 ```
+
+You can as well enable feature flag for a given gate:
+
+```ruby
+Feature.enable(:feature_flag_name, Project.find_by_full_path("root/my-project"))
+```