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

4 files changed, 34 insertions, 8 deletions

diff --git a/doc/development/feature_flags/controls.md b/doc/development/feature_flags/controls.md
index d4d1ec74591..9e7ce74cc0c 100644
--- a/doc/development/feature_flags/controls.md
+++ b/doc/development/feature_flags/controls.md
@@ -210,11 +210,20 @@ actors.
 Feature.enabled?(:some_feature, group)
 ```
 
-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. In that case, **Percentage of actors** rollout is a better method.
 
+Lastly, to verify that the feature is deemed stable in as many cases as possible,
+you should fully roll out the feature by enabling the flag **globally** by running:
+
+```shell
+/chatops run feature set some_feature true
+```
+
+This changes the feature flag state to be **enabled** always, which overrides the
+existing gates (e.g. `--group=gitlab-org`) in the above processes.
+
 ### Feature flag change logging
 
 Any feature flag change that affects GitLab.com (production) will
diff --git a/doc/development/feature_flags/development.md b/doc/development/feature_flags/development.md
index a44bc70439e..0b918478668 100644
--- a/doc/development/feature_flags/development.md
+++ b/doc/development/feature_flags/development.md
@@ -32,8 +32,8 @@ request removing the feature flag or the merge request where the default value o
 the feature flag is set to true. If the feature contains any DB migration it
 should include a changelog entry for DB changes.
 
-In the rare case that you need the feature flag to be on automatically, use
-`default_enabled: true` when checking:
+If you need the feature flag to be on automatically, use `default_enabled: true`
+when checking:
 
 ```ruby
 Feature.enabled?(:feature_flag, project, default_enabled: true)
diff --git a/doc/development/feature_flags/index.md b/doc/development/feature_flags/index.md
index bd0bd8f2018..0c1e34edc6f 100644
--- a/doc/development/feature_flags/index.md
+++ b/doc/development/feature_flags/index.md
@@ -1,6 +1,6 @@
 # Feature flags in development of GitLab
 
-[Feature Flags](../../user/project/operations/feature_flags.md)
+[Feature Flags](../../operations/feature_flags.md)
 can be used to gradually roll out changes, be
 it a new feature, or a performance improvement. By using feature flags, we can
 comfortably measure the impact of our changes, while still being able to easily
diff --git a/doc/development/feature_flags/process.md b/doc/development/feature_flags/process.md
index 57360f5b771..b053838964b 100644
--- a/doc/development/feature_flags/process.md
+++ b/doc/development/feature_flags/process.md
@@ -4,7 +4,7 @@
 
 This document only covers feature flags used in the development of GitLab
 itself. Feature flags in deployed user applications can be found at
-[Feature Flags feature documentation](../../user/project/operations/feature_flags.md).
+[Feature Flags feature documentation](../../operations/feature_flags.md).
 
 ## Feature flags in GitLab development
 
@@ -21,6 +21,19 @@ should be leveraged:
 - Merge requests that make changes hidden behind a feature flag, or remove an
   existing feature flag because a feature is deemed stable must have the
   ~"feature flag" label assigned.
+- When development of a feature will be spread across multiple merge
+  requests, you can use the following workflow:
+
+  1. Introduce a feature flag which is **off** by default, in the first merge request.
+  1. Submit incremental changes via one or more merge requests, ensuring that any
+     new code added can only be reached if the feature flag is **on**.
+     You can keep the feature flag enabled on your local GDK during development.
+  1. When the feature is ready to be tested, enable the feature flag for
+     a specific project and ensure that there are no issues with the implementation.
+  1. When the feature is ready to be announced, create a merge request that adds
+     documentation about the feature, including [documentation for the feature flag itself](../documentation/feature_flags.md),
+     and a changelog entry. In the same merge request either flip the feature flag to
+     be **on by default** or remove it entirely in order to enable the new behavior.
 
 One might be tempted to think that feature flags will delay the release of a
 feature by at least one month (= one release). This is not the case. A feature
@@ -29,6 +42,8 @@ flag does not have to stick around for a specific amount of time
 is deemed stable. Stable means it works on GitLab.com without causing any
 problems, such as outages.
 
+Please also read the [development guide for feature flags](development.md).
+
 ### When to use feature flags
 
 Starting with GitLab 11.4, developers are required to use feature flags for
@@ -56,7 +71,9 @@ absolutely no way to use the feature until it is enabled.
 In order to build a final release and present the feature for self-managed
 users, the feature flag should be at least defaulted to **on**. If the feature
 is deemed stable and there is confidence that removing the feature flag is safe,
-consider removing the feature flag altogether.
+consider removing the feature flag altogether. It's _strongly_ recommended that
+the feature flag is [enabled **globally** on **production**](./controls.md#enabling-a-feature-for-gitlabcom) for **at least one day**
+before making this decision. Unexpected bugs are sometimes discovered during this period.
 
 The process for enabling features that are disabled by default can take 5-6 days
 from when the merge request is first reviewed to when the change is deployed to
@@ -71,7 +88,7 @@ Take into consideration that such action can make the feature available on
 GitLab.com shortly after the change to the feature flag is merged.
 
 Changing the default state or removing the feature flag has to be done before
-the 22nd of the month, _at least_ 2 working days before, in order for the change
+the 22nd of the month, _at least_ 3-4 working days before, in order for the change
 to be included in the final self-managed release.
 
 In addition to this, the feature behind feature flag should: