diff options
Diffstat (limited to 'doc/development/feature_flags/index.md')
| -rw-r--r-- | doc/development/feature_flags/index.md | 26 |
1 files changed, 19 insertions, 7 deletions
diff --git a/doc/development/feature_flags/index.md b/doc/development/feature_flags/index.md index 560e4f8cb90..e18bcaa1f4e 100644 --- a/doc/development/feature_flags/index.md +++ b/doc/development/feature_flags/index.md @@ -15,12 +15,6 @@ This document provides guidelines on how to use feature flags in the GitLab codebase to conditionally enable features and test them. -Features that are developed and merged behind a feature flag -should not include a changelog entry. A changelog entry with `type: added` should be included in the merge -request removing the feature flag or the merge request where the default value of -the feature flag is set to enabled. If the feature contains any database migrations, it -*should* include a changelog entry for the database changes. - WARNING: All newly-introduced feature flags should be [disabled by default](https://about.gitlab.com/handbook/product-development-flow/feature-flag-lifecycle/#feature-flags-in-gitlab-development). @@ -55,7 +49,7 @@ should be leveraged: a specific project and ensure that there are no issues with the implementation. 1. When the feature is ready to be announced, create a merge request that adds documentation about the feature, including [documentation for the feature flag itself](../documentation/feature_flags.md), - and a changelog entry. In the same merge request either flip the feature flag to + and a [changelog entry](#changelog). In the same merge request either flip the feature flag to be **on by default** or remove it entirely in order to enable the new behavior. One might be tempted to think that feature flags will delay the release of a @@ -461,6 +455,24 @@ as follows: Feature.remove(:feature_flag_name) ``` +## Changelog + +- Any change behind a feature flag **disabled** by default **should not** have a changelog entry. + - **Exception:** database migrations **should** have a changelog entry. +- Any change related to a feature flag itself (flag removal, default-on setting) **should** have a changelog entry. + Use the flowchart to determine the changelog entry type. + + ```mermaid + graph LR + A[flag: default off] -->|'added' / 'changed'| B(flag: default on) + B -->|'other'| C(remove flag, keep new code) + B -->|'removed' / 'changed'| D(remove flag, keep old code) + A -->|'added' / 'changed'| C + A -->|no changelog| D + ``` + +- Any change behind a feature flag that is **enabled** by default **should** have a changelog entry. + ## Feature flags in tests Introducing a feature flag into the codebase creates an additional code path that should be tested. |