Add latest changes from gitlab-org/gitlab@master

2 files changed, 20 insertions, 10 deletions

diff --git a/doc/development/changelog.md b/doc/development/changelog.md
index f77f918d2a1..6412c303735 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 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.