Commit 0f27684a authored by Marcia Ramos's avatar Marcia Ramos

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
parents 90b4e466 391a46c0
---
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.
......@@ -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
......
---
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.
(...)
````
......@@ -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
......
......@@ -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
......
# 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).
......@@ -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.
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment