2020-04-21 21:09:38 +00:00
---
2020-08-21 18:10:24 +00:00
type: reference, dev
2021-08-05 21:10:12 +00:00
info: For assistance with this Style Guide page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-other-projects-and-subjects.
2020-04-21 21:09:38 +00:00
description: "GitLab development - how to document features deployed behind feature flags"
---
# Document features deployed behind feature flags
2021-07-30 18:09:08 +00:00
GitLab uses [feature flags ](../feature_flags/index.md ) to strategically roll
2020-04-21 21:09:38 +00:00
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.
2021-03-09 18:09:41 +00:00
Every feature introduced to the codebase, even if it's behind a feature flag,
must be documented. For context, see the
[latest merge request that updated this guideline ](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/47917#note_459984428 ).
2021-08-02 21:09:44 +00:00
When you document feature flags, you must:
- [Add a note at the start of the topic ](#use-a-note-to-describe-the-state-of-the-feature-flag ).
- [Add version history text ](#add-version-history-text ).
2021-07-30 18:09:08 +00:00
## Use a note to describe the state of the feature flag
2020-04-21 21:09:38 +00:00
2021-07-30 18:09:08 +00:00
Information about feature flags should be in a **Note** at the start of the topic (just below the version history).
2020-04-21 21:09:38 +00:00
2021-07-30 18:09:08 +00:00
The note has three parts, and follows this structure:
2020-04-21 21:09:38 +00:00
2021-07-30 18:09:08 +00:00
```markdown
2021-08-05 21:10:12 +00:00
FLAG:
2021-07-30 18:09:08 +00:00
< Self-managed GitLab availability information . > < GitLab.com availability information . >
< This feature is not ready for production use . >
2020-04-21 21:09:38 +00:00
```
2021-07-30 18:09:08 +00:00
### Self-managed GitLab availability information
2020-04-21 21:09:38 +00:00
2021-08-05 21:10:12 +00:00
| If the feature is... | Use this text |
|--------------------------|---------------|
2021-10-05 00:12:25 +00:00
| Available | `On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to [disable the feature flag](<path to>/administration/feature_flags.md) named <flag name>.` |
| Unavailable | `On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](<path to>/administration/feature_flags.md) named <flag name>.` |
| Available, per-group | `On self-managed GitLab, by default this feature is available. To hide the feature per group, ask an administrator to [disable the feature flag](<path to>/administration/feature_flags.md) named <flag name>.` |
| Unavailable, per-group | `On self-managed GitLab, by default this feature is not available. To make it available per group, ask an administrator to [enable the feature flag](<path to>/administration/feature_flags.md) named <flag name>.` |
| Available, per-project | `On self-managed GitLab, by default this feature is available. To hide the feature per project or for your entire instance, ask an administrator to [disable the feature flag](<path to>/administration/feature_flags.md) named <flag name>.` |
| Unavailable, per-project | `On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, ask an administrator to [enable the feature flag](<path to>/administration/feature_flags.md) named <flag name>.` |
| Available, per-user | `On self-managed GitLab, by default this feature is available. To hide the feature per user, ask an administrator to [disable the feature flag](<path to>/administration/feature_flags.md) named <flag name>.` |
| Unavailable, per-user | `On self-managed GitLab, by default this feature is not available. To make it available per user, ask an administrator to [enable the feature flag](<path to>/administration/feature_flags.md) named <flag name>.` |
2020-04-21 21:09:38 +00:00
2021-07-30 18:09:08 +00:00
### GitLab.com availability information
2020-04-21 21:09:38 +00:00
2021-08-05 21:10:12 +00:00
| If the feature is... | Use this text |
|-------------------------------------|---------------|
| Available | `On GitLab.com, this feature is available.` |
| Available to GitLab.com admins only | `On GitLab.com, this feature is available but can be configured by GitLab.com administrators only.`
| Unavailable | `On GitLab.com, this feature is not available.` |
2020-04-21 21:09:38 +00:00
2021-07-30 18:09:08 +00:00
### Optional information
2020-04-21 21:09:38 +00:00
2021-07-30 18:09:08 +00:00
If needed, you can add this sentence:
2020-04-21 21:09:38 +00:00
2021-11-23 15:11:19 +00:00
`The feature is not ready for production use.`
2020-08-21 18:10:24 +00:00
2021-07-30 18:09:08 +00:00
## Add version history text
2020-08-21 18:10:24 +00:00
2021-07-30 18:09:08 +00:00
When the state of a flag changes (for example, disabled by default to enabled by default), add the change to the version history.
2020-04-21 21:09:38 +00:00
2021-07-30 18:09:08 +00:00
Possible version history entries are:
2020-08-21 18:10:24 +00:00
```markdown
2021-10-05 00:12:25 +00:00
> - [Introduced](issue-link) in GitLab X.X [with a flag](../../administration/feature_flags.md) named <flag name>. Disabled by default.
2021-08-30 18:10:36 +00:00
> - [Enabled on GitLab.com](issue-link) in GitLab X.X.
> - [Enabled on GitLab.com](issue-link) in GitLab X.X. Available to GitLab.com administrators only.
> - [Enabled on self-managed](issue-link) in GitLab X.X.
2021-10-29 18:13:13 +00:00
> - [Generally available](issue-link) in GitLab X.Y. [Feature flag <flag name>](issue-link) removed.
2020-08-21 18:10:24 +00:00
```
2021-11-02 18:12:13 +00:00
You can combine entries if they happened in the same release:
```markdown
> - Introduced in GitLab 14.2 [with a flag](../../administration/feature_flags.md) named `ci_include_rules`. Disabled by default.
> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/337507) in GitLab 14.3.
```
2021-07-30 18:09:08 +00:00
## Feature flag documentation examples
2020-08-21 18:10:24 +00:00
2021-07-30 18:09:08 +00:00
The following examples show the progression of a feature flag.
2020-08-21 18:10:24 +00:00
2021-07-30 18:09:08 +00:00
```markdown
2021-10-05 00:12:25 +00:00
> Introduced in GitLab 13.7 [with a flag](../../administration/feature_flags.md) named `forti_token_cloud`. Disabled by default.
2020-04-21 21:09:38 +00:00
2021-08-05 21:10:12 +00:00
FLAG:
2021-07-30 18:09:08 +00:00
On self-managed GitLab, by default this feature is not available. To make it available,
2021-11-16 12:10:23 +00:00
ask an administrator to [enable the feature flag ](../administration/feature_flags.md ) named `forti_token_cloud` .
2021-07-30 18:09:08 +00:00
The feature is not ready for production use.
2020-08-21 18:10:24 +00:00
```
2021-08-30 18:10:36 +00:00
When the feature is enabled in production, you can update the version history:
2020-08-21 18:10:24 +00:00
2021-07-30 18:09:08 +00:00
```markdown
2021-10-05 00:12:25 +00:00
> - Introduced in GitLab 13.7 [with a flag](../../administration/feature_flags.md) named `forti_token_cloud`. Disabled by default.
2021-08-30 18:10:36 +00:00
> - [Enabled on self-managed](https://gitlab.com/issue/etc) GitLab 13.8.
2020-08-21 18:10:24 +00:00
2021-08-05 21:10:12 +00:00
FLAG:
2021-07-30 18:09:08 +00:00
On self-managed GitLab, by default this feature is available. To hide the feature per user,
2021-10-05 00:12:25 +00:00
ask an administrator to [disable the feature flag ](../administration/feature_flags.md ) named `forti_token_cloud` .
2020-08-21 18:10:24 +00:00
```
2021-07-30 18:09:08 +00:00
And, when the feature is done and fully available to all users:
2020-08-21 18:10:24 +00:00
2021-07-30 18:09:08 +00:00
```markdown
2021-10-05 00:12:25 +00:00
> - Introduced in GitLab 13.7 [with a flag](../../administration/feature_flags.md) named `forti_token_cloud`. Disabled by default.
2021-11-23 15:11:19 +00:00
> - [Enabled on self-managed](https://gitlab.com/issue/etc) in GitLab 13.8.
2021-08-30 18:10:36 +00:00
> - [Enabled on GitLab.com](https://gitlab.com/issue/etc) in GitLab 13.9.
2021-10-29 18:13:13 +00:00
> - [Generally available](issue-link) in GitLab 14.0. [Feature flag <flag name>](issue-link) removed.
2020-04-21 21:09:38 +00:00
```