Add latest changes from gitlab-org/gitlab@13-9-stable-eev13.9.0-rc42

4 files changed, 77 insertions, 14 deletions

diff --git a/doc/development/feature_flags/controls.md b/doc/development/feature_flags/controls.md
index adcf3175c45..21ac152c469 100644
--- a/doc/development/feature_flags/controls.md
+++ b/doc/development/feature_flags/controls.md
@@ -11,12 +11,12 @@ info: "See the Technical Writers assigned to Development Guidelines: https://abo
 
 To be able to turn on/off features behind feature flags in any of the
 GitLab Inc. provided environments such as staging and production, you need to
-have access to the [Chatops](../chatops_on_gitlabcom.md) bot. The Chatops bot
+have access to the [ChatOps](../chatops_on_gitlabcom.md) bot. The ChatOps bot
 is currently running on the ops instance, which is different from <https://gitlab.com> or <https://dev.gitlab.org>.
 
-Follow the Chatops document to [request access](../chatops_on_gitlabcom.md#requesting-access).
+Follow the ChatOps document to [request access](../chatops_on_gitlabcom.md#requesting-access).
 
-Once you are added to the project test if your access propagated,
+After you are added to the project test if your access propagated,
 run:
 
 ```shell
@@ -37,7 +37,7 @@ easier to measure the impact of both separately.
 The GitLab feature library (using
 [Flipper](https://github.com/jnunemaker/flipper), and covered in the [Feature
 Flags process](process.md) guide) supports rolling out changes to a percentage of
-time to users. This in turn can be controlled using [GitLab Chatops](../../ci/chatops/README.md).
+time to users. This in turn can be controlled using [GitLab ChatOps](../../ci/chatops/index.md).
 
 For an up to date list of feature flag commands please see [the source
 code](https://gitlab.com/gitlab-com/chatops/blob/master/lib/chatops/commands/feature.rb).
@@ -48,7 +48,7 @@ If you get an error "Whoops! This action is not allowed. This incident
 will be reported." that means your Slack account is not allowed to
 change feature flags or you do not [have access](#access).
 
-### Enabling a feature for preproduction testing
+### Enabling a feature for pre-production testing
 
 As a first step in a feature rollout, you should enable the feature on <https://about.staging.gitlab.com>
 and <https://dev.gitlab.org>.
@@ -62,7 +62,7 @@ a (very) rough estimate of how your feature will look/behave on GitLab.com.
 Both of these instances are connected to Sentry so make sure you check the projects
 there for any exceptions while testing your feature after enabling the feature flag.
 
-For these preproduction environments, the commands should be run in a
+For these pre-production environments, the commands should be run in a
 Slack channel for the stage the feature is relevant to. For example, use the
 `#s_monitor` channel for features developed by the Monitor stage, Health
 group.
@@ -77,7 +77,7 @@ To enable a feature for 25% of all users, run the following in Slack:
 ### Enabling a feature for GitLab.com
 
 When a feature has successfully been
-[enabled on a preproduction](#enabling-a-feature-for-preproduction-testing)
+[enabled on a pre-production](#enabling-a-feature-for-pre-production-testing)
 environment and verified as safe and working, you can roll out the
 change to GitLab.com (production).
 
@@ -226,11 +226,27 @@ you should fully roll out the feature by enabling the flag **globally** by runni
 This changes the feature flag state to be **enabled** always, which overrides the
 existing gates (e.g. `--group=gitlab-org`) in the above processes.
 
+##### Disabling feature flags
+
+To disable a feature flag that has been globally enabled you can run:
+
+```shell
+/chatops run feature set some_feature false
+```
+
+To disable a feature flag that has been enabled for a specific project you can run:
+
+```shell
+/chatops run feature set --group=gitlab-org some_feature false
+```
+
+You cannot selectively disable feature flags for a specific project/group/user without applying a [specific method of implementing](development.md#selectively-disable-by-actor) the feature flags.
+
 ### Feature flag change logging
 
-#### Chatops level
+#### ChatOps level
 
-Any feature flag change that affects GitLab.com (production) via [Chatops](https://gitlab.com/gitlab-com/chatops)
+Any feature flag change that affects GitLab.com (production) via [ChatOps](https://gitlab.com/gitlab-com/chatops)
 is automatically logged in an issue.
 
 The issue is created in the
@@ -243,7 +259,7 @@ The issue is then also posted to the GitLab internal
 marker to make the change even more visible.
 
 Changes to the issue format can be submitted in the
-[Chatops project](https://gitlab.com/gitlab-com/chatops).
+[ChatOps project](https://gitlab.com/gitlab-com/chatops).
 
 #### Instance level
 
diff --git a/doc/development/feature_flags/development.md b/doc/development/feature_flags/development.md
index dd732a08c72..0cdfa3e68d7 100644
--- a/doc/development/feature_flags/development.md
+++ b/doc/development/feature_flags/development.md
@@ -66,6 +66,13 @@ Feature.disabled?(:my_ops_flag, project, type: :ops)
 push_frontend_feature_flag(:my_ops_flag, project, type: :ops)
 ```
 
+### `experiment` type
+
+`experiment` feature flags are used for A/B testing on GitLab.com.
+
+An `experiment` feature flag should conform to the same standards as a `development` feature flag,
+although the interface has some differences. More information can be found in the [experiment guide](../experiment_guide/index.md).
+
 ## Feature flag definition and validation
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229161) in GitLab 13.3.
@@ -321,6 +328,28 @@ Feature.enabled?(:feature_flag, group)
 Feature.enabled?(:feature_flag, user)
 ```
 
+#### Selectively disable by actor
+
+By default you cannot selectively disable a feature flag by actor.
+
+```shell
+# This will not work how you would expect.
+/chatops run feature set some_feature true
+/chatops run feature set --project=gitlab-org/gitlab some_feature false
+```
+
+However, if you add two feature flags, you can write your conditional statement in such a way that the equivalent selective disable is possible.
+
+```ruby
+Feature.enabled?(:a_feature, project) && Feature.disabled?(:a_feature_override, project)
+```
+
+```shell
+# This will enable a feature flag globally, except for gitlab-org/gitlab
+/chatops run feature set a_feature true
+/chatops run feature set --project=gitlab-org/gitlab a_feature_override true
+```
+
 ### Enable additional objects as actors
 
 To use feature gates based on actors, the model needs to respond to
@@ -398,6 +427,9 @@ to ensure the feature works properly.
 
 When using the testing environment, all feature flags are enabled by default.
 
+WARNING:
+This does not apply to end-to-end (QA) tests, which [do not disable feature flags by default](#end-to-end-qa-tests). There is a different [process for using feature flags in end-to-end tests](../testing_guide/end_to_end/feature_flags.md).
+
 To disable a feature flag in a test, use the `stub_feature_flags`
 helper. For example, to globally disable the `ci_live_trace` feature
 flag in a test:
@@ -545,3 +577,17 @@ 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`.
+
+### End-to-end (QA) tests
+
+Toggling feature flags works differently in end-to-end (QA) tests. The end-to-end test framework does not have direct access to
+Rails or the database, so it can't use Flipper. Instead, it uses [the public API](../../api/features.md#set-or-create-a-feature). Each end-to-end test can [enable or disable a feature flag during the test](../testing_guide/end_to_end/feature_flags.md). Alternatively, you can enable or disable a feature flag before one or more tests when you [run them from your GitLab repository's `qa` directory](https://gitlab.com/gitlab-org/gitlab/tree/master/qa#running-tests-with-a-feature-flag-enabled-or-disabled), or if you [run the tests via GitLab QA](https://gitlab.com/gitlab-org/gitlab-qa/-/blob/master/docs/what_tests_can_be_run.md#running-tests-with-a-feature-flag-enabled).
+
+[As noted above, feature flags are not enabled by default in end-to-end tests.](#feature-flags-in-tests)
+This means that end-to-end tests will run with feature flags in the default state implemented in the source
+code, or with the feature flag in its current state on the GitLab instance under test, unless the
+test is written to enable/disable a feature flag explicitly.
+
+When a feature flag is changed on Staging or on GitLab.com, a Slack message will be posted to the `#qa-staging` or `#qa-production` channels to inform
+the pipeline triage DRI so that they can more easily determine if any failures are related to a feature flag change. However, if you are working on a change you can
+help to avoid unexpected failures by [confirming that the end-to-end tests pass with a feature flag enabled.](../testing_guide/end_to_end/feature_flags.md#confirming-that-end-to-end-tests-pass-with-a-feature-flag-enabled)
diff --git a/doc/development/feature_flags/index.md b/doc/development/feature_flags/index.md
index e93a5b3de1b..4890cc5da35 100644
--- a/doc/development/feature_flags/index.md
+++ b/doc/development/feature_flags/index.md
@@ -31,7 +31,8 @@ In all cases, those working on the changes should ask themselves:
 
 > Why do I need to add a feature flag? If I don't add one, what options do I have to control the impact on application reliability, and user experience?
 
-For perspective on why we limit our use of feature flags please see the following [video](https://www.youtube.com/watch?v=DQaGqyolOd8). 
+For perspective on why we limit our use of feature flags please see
+<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Feature flags only when needed](https://www.youtube.com/watch?v=DQaGqyolOd8).
 
 In case you are uncertain if a feature flag is necessary, simply ask about this in an early merge request, and those reviewing the changes will likely provide you with an answer.
 
diff --git a/doc/development/feature_flags/process.md b/doc/development/feature_flags/process.md
index 7e6299c193c..65a6d01e0a2 100644
--- a/doc/development/feature_flags/process.md
+++ b/doc/development/feature_flags/process.md
@@ -155,7 +155,7 @@ It may seem like feature flags are configuration, which goes against our [conven
 principle. However, configuration is by definition something that is user-manageable.
 Feature flags are not intended to be user-editable. Instead, they are intended as a tool for Engineers
 and Site Reliability Engineers to use to de-risk their changes. Feature flags are the shim that gets us
-to Continuous Delivery with our mono repo and without having to deploy the entire codebase on every change. 
+to Continuous Delivery with our monorepo and without having to deploy the entire codebase on every change.
 Feature flags are created to ensure that we can safely rollout our work on our terms.
 If we use Feature Flags as a configuration, we are doing it wrong and are indeed in violation of our
 principles. If something needs to be configured, we should intentionally make it configuration from the
@@ -173,5 +173,5 @@ Some of the benefits of using development-type feature flags are:
 1. Improved throughput: when a change is less risky because a flag exists, theoretical tests about
    scalability can potentially become unnecessary or less important. This allows an engineer to
    potentially test a feature on a small project, monitor the impact, and proceed. The alternative might
-   be to build complex benchmarks locally, or on staging, or on another GitLab deployment, which has an
-   outsized impact on the time it can take to build and release a feature.
+   be to build complex benchmarks locally, or on staging, or on another GitLab deployment, which has a
+   large impact on the time it can take to build and release a feature.