Add latest changes from gitlab-org/gitlab@master

2 files changed, 15 insertions, 0 deletions

diff --git a/doc/development/feature_flags/controls.md b/doc/development/feature_flags/controls.md
index d341cb3f1ba..b721707e07b 100644
--- a/doc/development/feature_flags/controls.md
+++ b/doc/development/feature_flags/controls.md
@@ -70,6 +70,8 @@ there for any exceptions while testing your feature after enabling the feature f
 For these pre-production environments, it's strongly encouraged to run the command in
 `#staging`, `#production`, or `#chatops-ops-test`, for improved visibility.
 
+#### Enabling the feature flag with percentage of time
+
 To enable a feature for 25% of the time, run the following in Slack:
 
 ```shell
@@ -77,6 +79,11 @@ To enable a feature for 25% of the time, run the following in Slack:
 /chatops run feature set new_navigation_bar 25 --random --staging
 ```
 
+NOTE:
+Percentage of time feature flags are deprecated in favor of [percentage of actors](#percentage-based-actor-selection).
+If you understand the consequences of using percentage of time feature flags, you can force it using
+`--ignore-random-deprecation-check`.
+
 ### Enabling a feature for GitLab.com
 
 When a feature has successfully been
@@ -130,6 +137,11 @@ To enable a feature for 25% of the time, run the following in Slack:
 /chatops run feature set new_navigation_bar 25 --random
 ```
 
+NOTE:
+Percentage of time feature flags are deprecated in favor of [percentage of actors](#percentage-based-actor-selection).
+If you understand the consequences of using percentage of time feature flags, you can force it using
+`--ignore-random-deprecation-check`.
+
 This sets a feature flag to `true` based on the following formula:
 
 ```ruby
diff --git a/doc/development/feature_flags/index.md b/doc/development/feature_flags/index.md
index 13dccc485d1..f966395edb4 100644
--- a/doc/development/feature_flags/index.md
+++ b/doc/development/feature_flags/index.md
@@ -15,6 +15,9 @@ view [this feature flags information](../../operations/feature_flags.md) instead
 WARNING:
 All newly-introduced feature flags should be [disabled by default](https://about.gitlab.com/handbook/product-development-flow/feature-flag-lifecycle/#feature-flags-in-gitlab-development).
 
+WARNING:
+All newly-introduced feature flags should be [used with an actor](controls.md#percentage-based-actor-selection).
+
 This document is the subject of continued work as part of an epic to [improve internal usage of feature flags](https://gitlab.com/groups/gitlab-org/-/epics/3551). Raise any suggestions as new issues and attach them to the epic.
 
 For an [overview of the feature flag lifecycle](https://about.gitlab.com/handbook/product-development-flow/feature-flag-lifecycle/#feature-flag-lifecycle), or if you need help deciding [if you should use a feature flag](https://about.gitlab.com/handbook/product-development-flow/feature-flag-lifecycle/#when-to-use-feature-flags) or not, please see the [feature flag lifecycle](https://about.gitlab.com/handbook/product-development-flow/feature-flag-lifecycle/) handbook page.