Commit 9a7e999f authored by Craig Norris's avatar Craig Norris

Merge branch 'docs-feature-flag-note' into 'master'

Updated feature flag documentation guidance

See merge request gitlab-org/gitlab!66783
parents 30088a63 c00d6a18
...@@ -31,16 +31,27 @@ These features can be enabled and disabled to allow or disallow users to use ...@@ -31,16 +31,27 @@ 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 them. It can be done by GitLab administrators with access to GitLab Rails
console. console.
When you disable a feature flag, the feature is hidden from users and all of the functionality is turned off.
For example, data is not recorded and services do not run.
If you used a certain feature and identified a bug, a misbehavior, or an If you used a certain feature and identified a bug, a misbehavior, or an
error, it's very important that you [**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) to GitLab as soon error, it's very important that you [**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) to GitLab as soon
as possible so we can improve or fix it while behind a flag. When you upgrade 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. GitLab to an earlier version, the feature flag status may change.
WARNING: ## Risks when enabling features still in development
Features deployed behind feature flags may not be ready for
production use. However, disabling features behind flags that were deployed Features that are disabled by default may change or be removed without notice in a future version of GitLab.
enabled by default may also present a risk. If they're enabled, we recommend
you leave them as-is. 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.
## How to enable and disable features behind flags ## How to enable and disable features behind flags
......
...@@ -491,7 +491,7 @@ A runner's registration fails if it exceeds the limit for the scope determined b ...@@ -491,7 +491,7 @@ A runner's registration fails if it exceeds the limit for the scope determined b
> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-job-log-limits). **(FREE SELF)** > - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-job-log-limits). **(FREE SELF)**
This in-development feature might not be available for your use. There can be This in-development feature might not be available for your use. There can be
[risks when enabling features still in development](../user/feature_flags.md#risks-when-enabling-features-still-in-development). [risks when enabling features still in development](../administration/feature_flags.md#risks-when-enabling-features-still-in-development).
Refer to this feature's version history for more details. Refer to this feature's version history for more details.
The job log file size limit is 100 megabytes by default. Any job that exceeds this value is dropped. The job log file size limit is 100 megabytes by default. Any job that exceeds this value is dropped.
......
...@@ -13,7 +13,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w ...@@ -13,7 +13,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-custom-emoji-api). **(FREE SELF)** > - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-custom-emoji-api). **(FREE SELF)**
This in-development feature might not be available for your use. There can be This in-development feature might not be available for your use. There can be
[risks when enabling features still in development](../../user/feature_flags.md#risks-when-enabling-features-still-in-development). [risks when enabling features still in development](../../administration/feature_flags.md#risks-when-enabling-features-still-in-development).
Refer to this feature's version history for more details. Refer to this feature's version history for more details.
To use custom emoji in comments and descriptions, you can add them to a group using the GraphQL API. To use custom emoji in comments and descriptions, you can add them to a group using the GraphQL API.
......
...@@ -14,7 +14,7 @@ type: concepts, howto ...@@ -14,7 +14,7 @@ type: concepts, howto
> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](../ci/environments/protected_environments.md#enable-or-disable-group-level-protected-environments). **(FREE SELF)** > - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](../ci/environments/protected_environments.md#enable-or-disable-group-level-protected-environments). **(FREE SELF)**
This in-development feature might not be available for your use. There can be This in-development feature might not be available for your use. There can be
[risks when enabling features still in development](../user/feature_flags.md#risks-when-enabling-features-still-in-development). [risks when enabling features still in development](../administration/feature_flags.md#risks-when-enabling-features-still-in-development).
Refer to this feature's version history for more details. Refer to this feature's version history for more details.
Read more about [group-level protected environments](../ci/environments/protected_environments.md#group-level-protected-environments), Read more about [group-level protected environments](../ci/environments/protected_environments.md#group-level-protected-environments),
......
...@@ -254,7 +254,7 @@ tries to steal tokens from other jobs. ...@@ -254,7 +254,7 @@ tries to steal tokens from other jobs.
> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-ci-job-token-scope-limit). **(FREE SELF)** > - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-ci-job-token-scope-limit). **(FREE SELF)**
This in-development feature might not be available for your use. There can be This in-development feature might not be available for your use. There can be
[risks when enabling features still in development](../user/feature_flags.md#risks-when-enabling-features-still-in-development). [risks when enabling features still in development](../administration/feature_flags.md#risks-when-enabling-features-still-in-development).
Refer to this feature's version history for more details. Refer to this feature's version history for more details.
You can limit the access scope of a project's CI/CD job token to increase the You can limit the access scope of a project's CI/CD job token to increase the
......
...@@ -163,7 +163,7 @@ For more information, see [Deployment safety](deployment_safety.md). ...@@ -163,7 +163,7 @@ For more information, see [Deployment safety](deployment_safety.md).
> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-group-level-protected-environments). **(FREE SELF)** > - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-group-level-protected-environments). **(FREE SELF)**
This in-development feature might not be available for your use. There can be This in-development feature might not be available for your use. There can be
[risks when enabling features still in development](../../user/feature_flags.md#risks-when-enabling-features-still-in-development). [risks when enabling features still in development](../../administration/feature_flags.md#risks-when-enabling-features-still-in-development).
Refer to this feature's version history for more details. Refer to this feature's version history for more details.
Typically, large enterprise organizations have an explicit permission boundary Typically, large enterprise organizations have an explicit permission boundary
......
...@@ -362,7 +362,7 @@ you visualize the entire pipeline, including all cross-project inter-dependencie ...@@ -362,7 +362,7 @@ you visualize the entire pipeline, including all cross-project inter-dependencie
> - To disable in GitLab self-managed instances, ask a GitLab administrator to [disable it](#enable-or-disable-job-dependency-view). **(FREE SELF)** > - To disable in GitLab self-managed instances, ask a GitLab administrator to [disable it](#enable-or-disable-job-dependency-view). **(FREE SELF)**
This in-development feature might not be available for your use. There can be This in-development feature might not be available for your use. There can be
[risks when enabling features still in development](../../user/feature_flags.md#risks-when-enabling-features-still-in-development). [risks when enabling features still in development](../../administration/feature_flags.md#risks-when-enabling-features-still-in-development).
Refer to this feature's version history for more details. Refer to this feature's version history for more details.
You can arrange jobs in the pipeline graph based on their [`needs`](../yaml/index.md#needs) You can arrange jobs in the pipeline graph based on their [`needs`](../yaml/index.md#needs)
......
...@@ -474,7 +474,7 @@ Use local includes instead of symbolic links. ...@@ -474,7 +474,7 @@ Use local includes instead of symbolic links.
> - For GitLab self-managed instances, GitLab administrators can opt to disable it. **(CORE ONLY)** > - For GitLab self-managed instances, GitLab administrators can opt to disable it. **(CORE ONLY)**
There can be There can be
[risks when disabling released features](../../user/feature_flags.md#risks-when-disabling-released-features). [risks when disabling released features](../../administration/feature_flags.md#risks-when-disabling-released-features).
Refer to this feature's version history for more details. Refer to this feature's version history for more details.
You can use wildcard paths (`*` and `**`) with `include:local`. You can use wildcard paths (`*` and `**`) with `include:local`.
......
...@@ -13,7 +13,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w ...@@ -13,7 +13,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
> - Recommended for production use. > - Recommended for production use.
> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-batched-background-migrations). **(FREE SELF)** > - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-batched-background-migrations). **(FREE SELF)**
There can be [risks when disabling released features](../../../user/feature_flags.md#risks-when-disabling-released-features). There can be [risks when disabling released features](../../../administration/feature_flags.md#risks-when-disabling-released-features).
Refer to this feature's version history for more details. Refer to this feature's version history for more details.
To update database tables in batches, GitLab can use batched background migrations. These migrations To update database tables in batches, GitLab can use batched background migrations. These migrations
...@@ -54,7 +54,7 @@ Feature.disable(:execute_batched_migrations_on_schedule) ...@@ -54,7 +54,7 @@ Feature.disable(:execute_batched_migrations_on_schedule)
> - Recommended for production use. > - Recommended for production use.
> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-automatic-batch-size-optimization). **(FREE SELF)** > - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-automatic-batch-size-optimization). **(FREE SELF)**
There can be [risks when disabling released features](../../../user/feature_flags.md#risks-when-disabling-released-features). There can be [risks when disabling released features](../../../administration/feature_flags.md#risks-when-disabling-released-features).
Refer to this feature's version history for more details. Refer to this feature's version history for more details.
To maximize throughput of batched background migrations (in terms of the number of tuples updated per time unit), batch sizes are automatically adjusted based on how long the previous batches took to complete. To maximize throughput of batched background migrations (in terms of the number of tuples updated per time unit), batch sizes are automatically adjusted based on how long the previous batches took to complete.
......
...@@ -125,7 +125,7 @@ WARNING: ...@@ -125,7 +125,7 @@ WARNING:
This feature might not be available to you. Check the **version history** note above for details. This feature might not be available to you. Check the **version history** note above for details.
There can be There can be
[risks when disabling released features](../../../user/feature_flags.md#risks-when-disabling-released-features). [risks when disabling released features](../../../administration/feature_flags.md#risks-when-disabling-released-features).
Refer to this feature's version history for more details. Refer to this feature's version history for more details.
To enable Dependency Scanning in a project, you can create a merge request To enable Dependency Scanning in a project, you can create a merge request
......
...@@ -20,21 +20,13 @@ may be unavailable to you. ...@@ -20,21 +20,13 @@ may be unavailable to you.
In this case, you'll see a warning like this in the feature documentation: In this case, you'll see a warning like this in the feature documentation:
This in-development feature might not be available for your use. There can be 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). [risks when enabling features still in development](../administration/feature_flags.md#risks-when-enabling-features-still-in-development).
Refer to this feature's version history for more details. Refer to this feature's version history for more details.
In the version history note, you'll find information on the state of the 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 feature flag, including whether the feature is on ("enabled by default") or
off ("disabled by default") for self-managed GitLab instances and for users of off ("disabled by default") for self-managed GitLab instances and for users of
GitLab.com. To see the full notes: GitLab.com.
1. Click the three-dots icon (ellipsis) to expand version history notes:
![Version history note with FF information](img/version_history_notes_collapsed_v13_2.png)
1. Read the version history information:
![Version history note with FF information](img/feature_flags_history_note_info_v13_2.png)
If you're a user of a GitLab self-managed instance and you want to try to use a If you're a user of a GitLab self-managed instance and you want to try to use a
disabled feature, you can ask a [GitLab administrator to enable it](../administration/feature_flags.md), disabled feature, you can ask a [GitLab administrator to enable it](../administration/feature_flags.md),
...@@ -42,17 +34,3 @@ although changing a feature's default state isn't recommended. ...@@ -42,17 +34,3 @@ 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 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. 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.
...@@ -41,7 +41,7 @@ In GitLab, iterations are similar to milestones, with a few differences: ...@@ -41,7 +41,7 @@ In GitLab, iterations are similar to milestones, with a few differences:
> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-iteration-cadences). **(PREMIUM SELF)** > - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-iteration-cadences). **(PREMIUM SELF)**
This in-development feature might not be available for your use. There can be This in-development feature might not be available for your use. There can be
[risks when enabling features still in development](../../feature_flags.md#risks-when-enabling-features-still-in-development). [risks when enabling features still in development](../../../administration/feature_flags.md#risks-when-enabling-features-still-in-development).
Refer to this feature's version history for more details. Refer to this feature's version history for more details.
Iteration cadences automate some common iteration tasks. They can be used to Iteration cadences automate some common iteration tasks. They can be used to
......
...@@ -233,7 +233,7 @@ and vice versa. ...@@ -233,7 +233,7 @@ and vice versa.
> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-graphql-based-issue-boards). **(FREE SELF)** > - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-graphql-based-issue-boards). **(FREE SELF)**
There can be There can be
[risks when disabling released features](../feature_flags.md#risks-when-disabling-released-features). [risks when disabling released features](../../administration/feature_flags.md#risks-when-disabling-released-features).
Refer to this feature's version history for more details. Refer to this feature's version history for more details.
Using GraphQL-based boards gives you these Using GraphQL-based boards gives you these
...@@ -345,7 +345,7 @@ As in other list types, click the trash icon to remove a list. ...@@ -345,7 +345,7 @@ As in other list types, click the trash icon to remove a list.
> - For GitLab self-managed instances, GitLab administrators can opt to disable the feature flags: [`board_new_list`](#enable-or-disable-new-add-list-form) and [`iteration_board_lists`](#enable-or-disable-iteration-lists-in-boards). **(PREMIUM SELF)** > - For GitLab self-managed instances, GitLab administrators can opt to disable the feature flags: [`board_new_list`](#enable-or-disable-new-add-list-form) and [`iteration_board_lists`](#enable-or-disable-iteration-lists-in-boards). **(PREMIUM SELF)**
There can be There can be
[risks when disabling released features](../feature_flags.md#risks-when-disabling-released-features). [risks when disabling released features](../../administration/feature_flags.md#risks-when-disabling-released-features).
Refer to this feature's version history for more details. Refer to this feature's version history for more details.
You're also able to create lists of an iteration. You're also able to create lists of an iteration.
...@@ -629,7 +629,7 @@ and the target list. ...@@ -629,7 +629,7 @@ and the target list.
> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-multi-selecting-issue-cards). **(FREE SELF)** > - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-multi-selecting-issue-cards). **(FREE SELF)**
This in-development feature might not be available for your use. There can be This in-development feature might not be available for your use. There can be
[risks when enabling features still in development](../feature_flags.md#risks-when-enabling-features-still-in-development). [risks when enabling features still in development](../../administration/feature_flags.md#risks-when-enabling-features-still-in-development).
Refer to this feature's version history for more details. Refer to this feature's version history for more details.
You can select multiple issue cards, then drag the group to another position within the list, or to You can select multiple issue cards, then drag the group to another position within the list, or to
......
...@@ -140,7 +140,7 @@ Feature.disable(:local_file_reviews) ...@@ -140,7 +140,7 @@ Feature.disable(:local_file_reviews)
> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-merge-request-conflicts-in-diff). **(FREE SELF)** > - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-merge-request-conflicts-in-diff). **(FREE SELF)**
This in-development feature might not be available for your use. There can be This in-development feature might not be available for your use. There can be
[risks when enabling features still in development](../../feature_flags.md#risks-when-enabling-features-still-in-development). [risks when enabling features still in development](../../../administration/feature_flags.md#risks-when-enabling-features-still-in-development).
Refer to this feature's version history for more details. Refer to this feature's version history for more details.
To avoid displaying the changes that are already on target branch in the diff, To avoid displaying the changes that are already on target branch in the diff,
......
...@@ -42,7 +42,7 @@ Previously merged commits can be added, but they can't be removed due to ...@@ -42,7 +42,7 @@ Previously merged commits can be added, but they can't be removed due to
[this bug](https://gitlab.com/gitlab-org/gitlab/-/issues/325538). [this bug](https://gitlab.com/gitlab-org/gitlab/-/issues/325538).
This in-development feature might not be available for your use. There can be This in-development feature might not be available for your use. There can be
[risks when enabling features still in development](../../feature_flags.md#risks-when-enabling-features-still-in-development). [risks when enabling features still in development](../../../administration/feature_flags.md#risks-when-enabling-features-still-in-development).
Refer to this feature's version history for more details. Refer to this feature's version history for more details.
When reviewing a merge request, it helps to have more context about the changes When reviewing a merge request, it helps to have more context about the changes
......
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