Skip to content
代码片段 群组 项目
未验证 提交 2fd768f3 编辑于 作者: Suzanne Selhorn's avatar Suzanne Selhorn 提交者： GitLab
浏览文件

Apply 2 suggestion(s) to 1 file(s) 


Co-authored-by: default avatarAshraf Khamis <akhamis@gitlab.com>
上级 b16211f6
No related branches found
No related tags found
无相关合并请求
隐藏空白变更内容
行内 左右并排
doc/development/documentation/feature_flags.md
+ 37
− 81
浏览文件 @ 2fd768f3
...@@ -36,10 +36,10 @@ even when the feature is not fully functional or otherwise documented. ...@@ -36,10 +36,10 @@ even when the feature is not fully functional or otherwise documented.
## How to add feature flag documentation ## How to add feature flag documentation
When you document feature flags, you must: To document feature flags:
- [Add history text](#add-history-text). - [Add history text](#add-history-text).
- [Use a note to describe the state of the feature flag](#use-a-note-to-describe-the-state-of-the-feature-flag). - [Add a flag note](#add-a-flag-note).
## Add history text ## Add history text
...@@ -50,119 +50,76 @@ Possible history entries are: ...@@ -50,119 +50,76 @@ Possible history entries are:
```markdown ```markdown
> - [Introduced](issue-link) in GitLab X.X [with a flag](../../administration/feature_flags.md) named `flag_name`. Disabled by default. > - [Introduced](issue-link) in GitLab X.X [with a flag](../../administration/feature_flags.md) named `flag_name`. Disabled by default.
> - [Enabled on self-managed](issue-link) in GitLab X.X.
> - [Enabled on GitLab.com](issue-link) in GitLab X.X. > - [Enabled on GitLab.com](issue-link) in GitLab X.X.
> - [Enabled on GitLab Dedicated](issue-link) in GitLab X.X. > - [Enabled on self-managed and GitLab Dedicated](issue-link) in GitLab X.X.
> - [Enabled on GitLab.com, self-managed, and GitLab Dedicated](issue-link) in GitLab X.X.
> - [Generally available](issue-link) in GitLab X.Y. Feature flag `flag_name` removed. > - [Generally available](issue-link) in GitLab X.Y. Feature flag `flag_name` removed.
``` ```
## Use a note to describe the state of the feature flag These entries might not fit every scenario. You can adjust to suit your needs.
For example, a flag might be enabled for a group, project, or subset of users only.
In that case, you can use a history entry like:
Information about feature flags should be in a `FLAG` note at the start of the topic (just below the history). `> - [Enabled on GitLab.com](issue-link) in GitLab X.X for a subset of users.`
The note has three required parts and one optional part. ## Add a flag note
The note follows this exact structure and order:
Add this feature flag note at the start of the topic, just below the history.
The final sentence (`not ready for production use`) is optional.
```markdown ```markdown
FLAG: FLAG:
<Self-managed GitLab availability information.> The availability of this feature is controlled by a feature flag.
<GitLab.com availability information.> For more information, see the history.
<GitLab Dedicated availability information.> This feature is available for testing, but not ready for production use.
<This feature is not ready for production use.>
``` ```
A `FLAG` note renders on the GitLab documentation site as: This note renders on the GitLab documentation site as:
FLAG: FLAG:
On self-managed GitLab, by default this feature is not available. The availability of this feature is controlled by a feature flag.
To make it available, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `example_flag`. For more information, see the history.
On GitLab.com and GitLab Dedicated, this feature is not available. This feature is available for testing, but not ready for production use.
This feature is not ready for production use.
### Self-managed GitLab availability information
| If the feature is... | Use this text |
|--------------------------|---------------|
| Available | ``On self-managed GitLab, by default this feature is available. To hide the feature, an administrator can [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, an administrator can [enable the feature flag](<path to>/administration/feature_flags.md) named `flag_name`.`` |
| Available to some users | ``On self-managed GitLab, by default this feature is available to a subset of users. To show or hide the feature for all, an administrator can [change the status of 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, an administrator can [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, an administrator can [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, an administrator can [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, an administrator can [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, an administrator can [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, an administrator can [enable the feature flag](<path to>/administration/feature_flags.md) named `flag_name`.`` |
### GitLab.com availability information
| If the feature is... | Use this text |
|---------------------------------------------|---------------|
| Available | `On GitLab.com, this feature is available.` |
| Available to GitLab.com administrators 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.` |
### GitLab Dedicated availability information
| If the feature is... | Use this text |
|---------------------------------------------|---------------|
| Available | `On GitLab Dedicated, this feature is available.` |
| Unavailable | `On GitLab Dedicated, this feature is not available.` |
- You can combine GitLab.com and GitLab Dedicated like this:
`On GitLab.com and GitLab Dedicated, this feature is not available.`
- If the feature is behind a flag that is disabled for self-managed GitLab,
the feature is not available for GitLab Dedicated.
### Optional information
If needed, you can add this sentence:
`This feature is not ready for production use.`
## Feature flag documentation examples ## History examples
The following examples show the progression of a feature flag. Update the history and the `FLAG` note with every change: The following examples show the progression of a feature flag. Update the history with every change:
```markdown ```markdown
> - [Introduced](issue-link) in GitLab 13.7 [with a flag](../../administration/feature_flags.md) named `forti_token_cloud`. Disabled by default. > - [Introduced](issue-link) in GitLab 13.7 [with a flag](../../administration/feature_flags.md) named `forti_token_cloud`. Disabled by default.
FLAG: FLAG:
On self-managed GitLab, by default this feature is not available. The availability of this feature is controlled by a feature flag. For more information, see the history.
To make it available, an administrator can [enable the feature flag](../administration/feature_flags.md) named `forti_token_cloud`.
On GitLab.com and GitLab Dedicated, this feature is not available.
``` ```
When the feature is enabled by default on self-managed and GitLab Dedicated: When the feature is enabled by default on GitLab.com:
```markdown ```markdown
> - [Introduced](issue-link) in GitLab 13.7 [with a flag](../../administration/feature_flags.md) named `forti_token_cloud`. Disabled by default. > - [Introduced](issue-link) in GitLab 13.7 [with a flag](../../administration/feature_flags.md) named `forti_token_cloud`. Disabled by default.
> - [Enabled on self-managed and GitLab Dedicated](issue-link) in GitLab 13.8. > - [Enabled on GitLab.com](issue-link) in GitLab 13.8.
FLAG: FLAG:
On self-managed GitLab, by default this feature is available. The availability of this feature is controlled by a feature flag. For more information, see the history.
To hide the feature, an administrator can [disable the feature flag](../administration/feature_flags.md) named `forti_token_cloud`.
On GitLab.com, this feature is not available. On GitLab Dedicated, this feature is available.
``` ```
When the feature is enabled by default for all offerings: When the feature is enabled by default for all offerings:
```markdown ```markdown
> - [Introduced](issue-link) in GitLab 13.7 [with a flag](../../administration/feature_flags.md) named `forti_token_cloud`. Disabled by default. > - [Introduced](issue-link) in GitLab 13.7 [with a flag](../../administration/feature_flags.md) named `forti_token_cloud`. Disabled by default.
> - [Enabled on self-managed and GitLab Dedicated](issue-link) in GitLab 13.8. > - [Enabled on GitLab.com](issue-link) in GitLab 13.8.
> - [Enabled on GitLab.com](issue-link) in GitLab 13.9. > - [Enabled on self-managed and GitLab Dedicated](issue-link) in GitLab 13.9.
FLAG: FLAG:
On self-managed GitLab, by default this feature is available. The availability of this feature is controlled by a feature flag. For more information, see the history.
To hide the feature, an administrator can [disable the feature flag](../administration/feature_flags.md) named `forti_token_cloud`.
On GitLab.com and GitLab Dedicated, this feature is available.
``` ```
When the flag is removed, add the `Generally available` entry and delete the `FLAG` note: When the flag is removed, add a `Generally available` entry. Ensure that you delete the `FLAG` note as well:
```markdown ```markdown
> - [Introduced](issue-link) in GitLab 13.7 [with a flag](../../administration/feature_flags.md) named `forti_token_cloud`. Disabled by default. > - [Introduced](issue-link) in GitLab 13.7 [with a flag](../../administration/feature_flags.md) named `forti_token_cloud`. Disabled by default.
> - [Enabled on self-managed and GitLab Dedicated](issue-link) in GitLab 13.8. > - [Enabled on GitLab.com](issue-link) in GitLab 13.8.
> - [Enabled on GitLab.com](issue-link) in GitLab 13.9. > - [Enabled on self-managed and GitLab Dedicated](issue-link) in GitLab 13.9.
> - [Generally available](issue-link) in GitLab 14.0. Feature flag `forti_token_cloud` removed. > - [Generally available](issue-link) in GitLab 14.0. Feature flag `forti_token_cloud` removed.
``` ```
...@@ -176,16 +133,15 @@ Combine entries if they happened in the same release: ...@@ -176,16 +133,15 @@ Combine entries if they happened in the same release:
```markdown ```markdown
> - [Introduced](issue-link) in GitLab 14.2 [with a flag](../../administration/feature_flags.md) named `ci_include_rules`. Disabled by default. > - [Introduced](issue-link) in GitLab 14.2 [with a flag](../../administration/feature_flags.md) named `ci_include_rules`. Disabled by default.
> - [Enabled on self-managed](issue-link) in GitLab 14.3.
> - [Enabled on GitLab.com](issue-link) in GitLab 14.3. > - [Enabled on GitLab.com](issue-link) in GitLab 14.3.
> - [Enabled on GitLab Dedicated](issue-link) in GitLab 14.3. > - [Enabled on self-managed and GitLab Dedicated](issue-link) in GitLab 14.3.
``` ```
- After: - After:
```markdown ```markdown
> - [Introduced](issue-link) in GitLab 14.2 [with a flag](../../administration/feature_flags.md) named `ci_include_rules`. Disabled by default. > - [Introduced](issue-link) in GitLab 14.2 [with a flag](../../administration/feature_flags.md) named `ci_include_rules`. Disabled by default.
> - [Enabled on self-managed, GitLab.com, and GitLab Dedicated](issue-link) in GitLab 14.3. > - [Enabled on GitLab.com, self-managed, and GitLab Dedicated](issue-link) in GitLab 14.3.
``` ```
Delete `Enabled on GitLab.com` entries only when the feature is enabled by default for all offerings and the flag is removed: Delete `Enabled on GitLab.com` entries only when the feature is enabled by default for all offerings and the flag is removed:
...@@ -194,8 +150,8 @@ Delete `Enabled on GitLab.com` entries only when the feature is enabled by defau ...@@ -194,8 +150,8 @@ Delete `Enabled on GitLab.com` entries only when the feature is enabled by defau
```markdown ```markdown
> - [Introduced](issue-link) in GitLab 15.6 [with a flag](../../administration/feature_flags.md) named `ci_hooks_pre_get_sources_script`. Disabled by default. > - [Introduced](issue-link) in GitLab 15.6 [with a flag](../../administration/feature_flags.md) named `ci_hooks_pre_get_sources_script`. Disabled by default.
> - [Enabled on self-managed and GitLab Dedicated](issue-link) in GitLab 15.7. > - [Enabled on GitLab.com](issue-link) in GitLab 15.7.
> - [Enabled on GitLab.com](issue-link) in GitLab 15.8. > - [Enabled on self-managed and GitLab Dedicated](issue-link) in GitLab 15.8.
> - [Generally available](issue-link) in GitLab 15.9. Feature flag `ci_hooks_pre_get_sources_script` removed. > - [Generally available](issue-link) in GitLab 15.9. Feature flag `ci_hooks_pre_get_sources_script` removed.
``` ```
...@@ -203,6 +159,6 @@ Delete `Enabled on GitLab.com` entries only when the feature is enabled by defau ...@@ -203,6 +159,6 @@ Delete `Enabled on GitLab.com` entries only when the feature is enabled by defau
```markdown ```markdown
> - [Introduced](issue-link) in GitLab 15.6 [with a flag](../../administration/feature_flags.md) named `ci_hooks_pre_get_sources_script`. Disabled by default. > - [Introduced](issue-link) in GitLab 15.6 [with a flag](../../administration/feature_flags.md) named `ci_hooks_pre_get_sources_script`. Disabled by default.
> - [Enabled on self-managed and GitLab Dedicated](issue-link) in GitLab 15.7. > - [Enabled on self-managed and GitLab Dedicated](issue-link) in GitLab 15.8.
> - [Generally available](issue-link) in GitLab 15.9. Feature flag `ci_hooks_pre_get_sources_script` removed. > - [Generally available](issue-link) in GitLab 15.9. Feature flag `ci_hooks_pre_get_sources_script` removed.
``` ```
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或