Merge branch 'docs-for-flagged-features' into 'master'

Docs: feature flags in GL development - admin and dev docs

Closes #213714

See merge request gitlab-org/gitlab!29062

doc/administration/feature_flags.md

+---
+type: reference
+description: "GitLab administrator: enable and disable GitLab features deployed behind feature flags"
+---
+
+# Enable and disable GitLab features deployed behind feature flags **(CORE ONLY)**
+
+GitLab adopted [feature flags strategies](../development/feature_flags/index.md)
+to deploy features in an early stage of development so that they can be
+incrementally rolled out.
+
+Before making them permanently available, features can be deployed behind
+flags for a [number of reasons](../development/feature_flags/process.md#when-to-use-feature-flags), such as:
+
+- To test the feature.
+- To get feedback from users and customers while in an early stage of the development of the feature.
+- To evaluate users adoption.
+- To evaluate how it impacts GitLab's performance.
+- To build it in smaller pieces throughout releases.
+
+Features behind flags can be gradually rolled out, typically:
+
+1. The feature starts disabled by default.
+1. The feature becomes enabled by default.
+1. The feature flag is removed.
+
+These features can be enabled and disabled to allow or disallow users to use
+them. It can be done by GitLab administrators with access to GitLab Rails
+console.
+
+If you used a certain feature and identified a bug, a misbehavior, or an
+error, it's very important that you **[provide feedback]** to GitLab as soon
+as possible so we can improve or fix it while behind a flag. When you upgrade
+GitLab to an earlier version, the feature flag status may change.
+
+[provide feedback]: https://gitlab.com/gitlab-org/gitlab/issues/new?issue[title]=Docs%20-%20feature%20flag%20feedback%3A%20Feature%20Name&issue[description]=Describe%20the%20problem%20you%27ve%20encountered.%0A%0A%3C!--%20Don%27t%20edit%20below%20this%20line%20--%3E%0A%0A%2Flabel%20~%22docs%5C-comments%22%20
+
+<!-- Note: the link identifier above was used to facilitate review and update. -->
+
+NOTE: **Note:**
+Mind that features deployed behind feature flags may not be ready for
+production use. However, disabling features behind flags that were deployed
+enabled by default may also present a risk. If they're enabled, we recommend
+you leave them as-is.
+
+## How to enable and disable features behind flags
+
+Each feature has its own flag that should be used to enable and disable it.
+The documentation of each feature behind a flag includes a section informing
+the status of the flag and the command to enable or disable it.
+
+### Start the GitLab Rails console
+
+The first thing you need to enable or disable a feature behind a flag is to
+start a session on GitLab Rails console.
+
+For Omnibus installations:
+
+```shell
+sudo gitlab-rails console
+```
+
+For installations from the source:
+
+```shell
+sudo -u git -H bundle exec rails console -e production
+```
+
+For details, see [starting a Rails console session](troubleshooting/debug.md#starting-a-rails-console-session).
+
+### Enable or disable the feature
+
+Once the Rails console session has started, run the `Feature.enable` or
+`Feature.disable` commands accordingly. The specific flag can be found
+in the feature's documentation itself.
+
+To enable a feature, run:
+
+```ruby
+Feature.enable(:<feature flag>)
+```
+
+Example, to enable Evidence Collection:
+
+```ruby
+Feature.enable(:release_evidence_collection)
+```
+
+To disable a feature, run:
+
+```ruby
+Feature.disable(:<feature flag>)
+```
+
+Example, to disable Evidence Collection:
+
+```ruby
+Feature.disable(:release_evidence_collection)
+```
+
+When the feature is ready, GitLab will remove the feature flag, the option for
+enabling and disabling it will no longer exist, and the feature will become
+available in all instances.

doc/administration/index.md

@@ -64,7 +64,8 @@ Learn how to install, configure, update, and maintain your GitLab instance.
 - [External Classification Policy Authorization](../user/admin_area/settings/external_authorization.md) **(PREMIUM ONLY)**
 - [Upload a license](../user/admin_area/license.md): Upload a license to unlock features that are in paid tiers of GitLab. **(STARTER ONLY)**
 - [Admin Area](../user/admin_area/index.md): for self-managed instance-wide configuration and maintenance.
-- [S/MIME Signing](smime_signing_email.md): how to sign all outgoing notification emails with S/MIME
+- [S/MIME Signing](smime_signing_email.md): how to sign all outgoing notification emails with S/MIME.
+- [Enabling and disabling features flags](feature_flags.md): how to enable and disable GitLab features deployed behind feature flags.
 
 #### Customizing GitLab's appearance
 

doc/development/documentation/feature_flags.md

+---
+type: reference
+description: "GitLab development - how to document features deployed behind feature flags"
+---
+
+# Document features deployed behind feature flags
+
+GitLab uses [Feature Flags](../feature_flags/index.md) to strategically roll
+out the deployment of its own features. The way we document a feature behind a
+feature flag depends on its state (enabled or disabled). When the state
+changes, the developer who made the change **must update the documentation**
+accordingly.
+
+## Criteria
+
+According to the process of [deploying GitLab features behind feature flags](../feature_flags/process.md):
+
+> - _By default, feature flags should be off._
+> - _Feature flags should remain in the codebase for a short period as possible to reduce the need for feature flag accounting._
+> - _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._
+
+See how to document them below, according to the state of the flag:
+
+- [Features disabled by default](#features-disabled-by-default).
+- [Features that became enabled by default](#features-that-became-enabled-by-default).
+- [Features directly enabled by default](#features-directly-enabled-by-default).
+- [Features with the feature flag removed](#features-with-flag-removed).
+
+NOTE: **Note:**
+The [`**(CORE ONLY)**`](styleguide.md#product-badges) badge or equivalent for
+the feature's tier should be added to the line and heading that refers to
+enabling/disabling feature flags as Admin access is required to do so,
+therefore, it indicates that it cannot be done by regular users of GitLab.com.
+
+### Features disabled by default
+
+For features disabled by default, if they cannot be used yet due to lack of
+completeness, or if they're still under internal evaluation (for example, for
+performance implications) do **not document them**: add (or merge) the docs
+only when the feature is safe and ready to use and test by end users.
+
+For feature flags disabled by default, if they can be used by end users:
+
+- Say that it's disabled by default.
+- Say whether it's enabled on GitLab.com.
+- Say whether it's recommended for production use.
+- Document how to enable and disable it.
+
+For example, for a feature disabled by default, disabled on GitLab.com, and
+not ready for production use:
+
+````md
+# Feature Name
+
+> - [Introduced](link-to-issue) in GitLab 12.0.
+> - It's deployed behind a feature flag, disabled by default.
+> - It's disabled on GitLab.com.
+> - It's not recommended for production use.
+> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#anchor-to-section). **(CORE ONLY)**
+
+(...)
+
+### Enable or disable <Feature Name> **(CORE ONLY)**
+
+<Feature Name> is under development and not ready for production use. It is
+deployed behind a feature flag that is **disabled by default**.
+[GitLab administrators with access to the GitLab Rails console](../path/to/administration/feature_flags.md)
+can enable it for your instance.
+
+To enable it:
+
+```ruby
+Feature.enable(:<feature flag>)
+```
+
+To disable it:
+
+```ruby
+Feature.disable(:<feature flag>)
+```
+````
+
+Adjust the blurb according to the state of the feature you're documenting.
+
+### Features that became enabled by default
+
+For features that became enabled by default:
+
+- Say that it became enabled by default.
+- Say whether it's enabled on GitLab.com.
+- Say whether it's recommended for production use.
+- Document how to disable and enable it.
+
+For example, for a feature initially deployed disabled by default, that became enabled by default, that is enabled on GitLab.com, and ready for production use:
+
+````md
+# Feature Name
+
+> - [Introduced](link-to-issue) in GitLab 12.0.
+> - It was deployed behind a feature flag, disabled by default.
+> - [Became enabled by default](link-to-issue) on GitLab 12.1.
+> - It's enabled on GitLab.com.
+> - It's recommended for production use.
+> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#anchor-to-section). **(CORE ONLY)**
+
+(...)
+
+### Enable or disable <Feature Name> **(CORE ONLY)**
+
+<Feature Name> is under development but ready for production use.
+It is deployed behind a feature flag that is **enabled by default**.
+[GitLab administrators with access to the GitLab Rails console](..path/to/administration/feature_flags.md)
+can opt to disable it for your instance.
+
+To disable it:
+
+```ruby
+Feature.disable(:<feature flag>)
+```
+
+To enable it:
+
+```ruby
+Feature.enable(:<feature flag>)
+```
+````
+
+Adjust the blurb according to the state of the feature you're documenting.
+
+### Features directly enabled by default
+
+For features enabled by default:
+
+- Say it's enabled by default.
+- Say whether it's enabled on GitLab.com.
+- Say whether it's recommended for production use.
+- Document how to disable and enable it.
+
+For example, for a feature enabled by default, enabled on GitLab.com, and ready for production use:
+
+````md
+# Feature Name
+
+> - [Introduced](link-to-issue) in GitLab 12.0.
+> - It's deployed behind a feature flag, enabled by default.
+> - It's enabled on GitLab.com.
+> - It's recommended for production use.
+> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#anchor-to-section). **(CORE ONLY)**
+
+(...)
+
+### Enable or disable <Feature Name> **(CORE ONLY)**
+
+<Feature Name> is under development but ready for production use.
+It is deployed behind a feature flag that is **enabled by default**.
+[GitLab administrators with access to the GitLab Rails console](..path/to/administration/feature_flags.md)
+can opt to disable it for your instance.
+
+To disable it:
+
+```ruby
+Feature.disable(:<feature flag>)
+```
+
+To enable it:
+
+```ruby
+Feature.enable(:<feature flag>)
+```
+````
+
+Adjust the blurb according to the state of the feature you're documenting.
+
+### Features with flag removed
+
+Once the feature is ready and the flag has been removed, clean up the
+documentation. Remove the feature flag mention keeping only a note that
+mentions the flag in the version history notes:
+
+````md
+# Feature Name
+
+> - [Introduced](link-to-issue) in GitLab 12.0.
+> - [Feature flag removed](link-to-issue) in GitLab 12.2.
+
+(...)
+
+````

doc/development/documentation/index.md

@@ -13,6 +13,7 @@ In addition to this page, the following resources can help you craft and contrib
 - [Documentation process](workflow.md).
 - [Markdown Guide](../../user/markdown.md) - A reference for all Markdown syntax supported by GitLab.
 - [Site architecture](site_architecture/index.md) - How <https://docs.gitlab.com> is built.
+- [Documentation for feature flags](feature_flags.md) - How to write and update documentation for GitLab features deployed behind feature flags.
 
 ## Source files and rendered web locations
 

doc/development/documentation/styleguide.md

@@ -1416,38 +1416,8 @@ can facilitate this by making sure the troubleshooting content addresses:
 
 ## Feature flags
 
-Sometimes features are shipped with feature flags, either:
-
-- On by default, but providing the option to turn the feature off.
-- Off by default, but providing the option to turn the feature on.
-
-When documenting feature flags for a feature, include:
-
-- Why a feature flag is necessary. Some of the reasons are
-  [outlined in the handbook](https://about.gitlab.com/handbook/product/#alpha-beta-ga).
-- That administrative access is required to make a feature flag change.
-- What to ask for when requesting a change to a feature flag's state.
-
-NOTE: **Note:**
-The [Product Manager for the relevant group](https://about.gitlab.com/handbook/product/categories/#devops-stages)
-must review and approve the addition or removal of any mentions of using feature flags before the doc change is merged.
-
-The following is sample text for adding feature flag documentation for a feature that is
-off by default:
-
-````md
-### Enabling the feature
-
-This feature comes with the `:feature_flag` feature flag disabled by default. In some cases,
-this feature is incompatible with an old configuration. To turn on the feature,
-ask a GitLab administrator with Rails console access to run the following command:
-
-```ruby
-Feature.enable(:feature_flag)
-```
-````
-
-For guidance on developing with feature flags, see
+Learn how to [document features deployed behind flags](feature_flags.md).
+For guidance on developing GitLab with feature flags, see
 [Feature flags in development of GitLab](../feature_flags/index.md).
 
 ## API

doc/development/feature_flags/index.md

 # Feature flags in development of GitLab
 
-Feature flags can be used to gradually roll out changes, be
+[Feature Flags](../../user/project/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
 disable those changes, without having to revert an entire release.
@@ -10,6 +11,5 @@ Before using feature flags for GitLab's development, read through the following:
 - [Process for using features flags](process.md).
 - [Developing with feature flags](development.md).
 - [Controlling feature flags](controls.md).
-
-When documenting feature flags, see [Feature flags](../documentation/styleguide.md#feature-flags)
-in the Documentation Style Guide.
+- [Documenting features deployed behind feature flags](../documentation/feature_flags.md).
+- [How GitLab administrators can enable and disable features behind flags](../../administration/feature_flags.md).

doc/development/feature_flags/process.md

@@ -63,6 +63,9 @@ from when the merge request is first reviewed to when the change is deployed to
 GitLab.com. However, it is recommended to allow 10-14 days for this activity to
 account for unforeseen problems.
 
+Feature flags must be [documented according to their state (enabled/disabled)](../documentation/feature_flags.md),
+and when the state changes, docs **must** be updated accordingly.
+
 NOTE: **Note:**
 Take into consideration that such action can make the feature available on
 GitLab.com shortly after the change to the feature flag is merged.