diff --git a/doc/development/changelog.md b/doc/development/changelog.md index f77f918d2a1bbd862e1640444ea8318d8fc32082..6412c3037358ce4bf25aa7060c69ea4b0664fd76 100644 --- a/doc/development/changelog.md +++ b/doc/development/changelog.md @@ -52,11 +52,9 @@ the `author` field. GitLab team members **should not**. a changelog entry regardless of these guidelines if the contributor wants one. Example: "Fixed a typo on the search results page." - Any docs-only changes **should not** have a changelog entry. -- Any change behind a feature flag **disabled** by default **should not** have a changelog entry. -- Any change behind a feature flag that is **enabled** by default **should** have a changelog entry. +- For changes related to feature flags, use [feature flag guide](feature_flags/index.md#changelog) to determine the changelog entry. - Any change that adds new Usage Data metrics, sets the status of existing ones to `removed`, and changes that need to be documented in Product Intelligence [Metrics Dictionary](usage_ping/dictionary.md) **should** have a changelog entry. - A change that adds snowplow events **should** have a changelog entry - -- A change that [removes a feature flag, or removes a feature and its feature flag](feature_flags/index.md) **must** have a changelog entry. - A fix for a regression introduced and then fixed in the same release (i.e., fixing a bug introduced during a monthly release candidate) **should not** have a changelog entry. diff --git a/doc/development/feature_flags/index.md b/doc/development/feature_flags/index.md index 560e4f8cb90016f0b1a91bbe71368aec73b755cd..e18bcaa1f4e447fe5cc58a106854de26d08c29b8 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.