Merge branch 'mk/warn-about-toggling-development-feature-flags' into 'master'

Warn about toggling development feature flags

See merge request gitlab-org/gitlab!55032

doc/development/documentation/feature_flags.md

@@ -67,8 +67,9 @@ be enabled for a single project, and is not ready for production use:
 > - Not recommended for production use.
 > - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#anchor-to-section). **(FREE SELF)**
 
-WARNING:
-This feature might not be available to you. Check the **version history** note above for details.
+This in-development feature might not be available for your use. There can be
+[risks when enabling features still in development](<replace with path to>/user/feature_flags.md#risks-when-enabling-features-still-in-development).
+Refer to this feature's version history for more details.
 
 (...Regular content goes here...)
 
@@ -126,8 +127,9 @@ use:
 > - Recommended for production use.
 > - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#anchor-to-section). **(FREE SELF)**
 
-WARNING:
-This feature might not be available to you. Check the **version history** note above for details.
+There can be
+[risks when disabling released features](<replace with path to>/user/feature_flags.md#risks-when-disabling-released-features).
+Refer to this feature's version history for more details.
 
 (...Regular content goes here...)
 
@@ -182,8 +184,9 @@ cannot be enabled for a single project, and is ready for production use:
 > - Recommended for production use.
 > - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#anchor-to-section). **(FREE SELF)**
 
-WARNING:
-This feature might not be available to you. Check the **version history** note above for details.
+There can be
+[risks when disabling released features](<replace with path to>/user/feature_flags.md#risks-when-disabling-released-features).
+Refer to this feature's version history for more details.
 
 (...Regular content goes here...)
 
@@ -255,8 +258,9 @@ be enabled by project, and is ready for production use:
 > - Recommended for production use.
 > - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#anchor-to-section). **(FREE SELF)**
 
-WARNING:
-This feature might not be available to you. Check the **version history** note above for details.
+There can be
+[risks when disabling released features](<replace with path to>/user/feature_flags.md#risks-when-disabling-released-features).
+Refer to this feature's version history for more details.
 
 (...Regular content goes here...)
 

doc/user/feature_flags.md

@@ -18,9 +18,9 @@ may be unavailable to you.
 
 In this case, you'll see a warning like this in the feature documentation:
 
-WARNING:
-This feature might not be available to you. Review the **version history** note
-on this page for details.
+This in-development feature might not be available for your use. There can be
+[risks when enabling features still in development](#risks-when-enabling-features-still-in-development).
+Refer to this feature's version history for more details.
 
 In the version history note, you'll find information on the state of the
 feature flag, including whether the feature is on ("enabled by default") or
@@ -41,3 +41,17 @@ although changing a feature's default state isn't recommended.
 
 If you're a GitLab.com user and the feature is disabled, be aware that GitLab may
 be working on the feature for potential release in the future.
+
+## Risks when enabling features still in development
+
+Features that are disabled by default may change or be removed without notice in a future version of GitLab.
+
+Data corruption, stability degradation, or performance degradation might occur if
+you enable a feature that's disabled by default. Problems caused by using a default
+disabled feature aren't covered by GitLab support, unless you were directed by GitLab
+to enable the feature.
+
+## Risks when disabling released features
+
+In most cases, the feature flag code is removed in a future version of GitLab.
+If and when that occurs, from that point onward you can't keep the feature in a disabled state.