Add latest changes from gitlab-org/gitlab@13-12-stable-eev13.12.0-rc42

2 files changed, 20 insertions, 8 deletions

diff --git a/doc/development/feature_flags/controls.md b/doc/development/feature_flags/controls.md
index c9538c38850..08a4401181b 100644
--- a/doc/development/feature_flags/controls.md
+++ b/doc/development/feature_flags/controls.md
@@ -266,7 +266,7 @@ Changes to the issue format can be submitted in the
 Any feature flag change that affects any GitLab instance is automatically logged in
 [features_json.log](../../administration/logs.md#features_jsonlog).
 You can search the change history in [Kibana](https://about.gitlab.com/handbook/support/workflows/kibana.html).
-You can access the feature flag change history for GitLab.com [here](https://log.gprd.gitlab.net/goto/d060337c017723084c6d97e09e591fc6).
+You can also access the feature flag change history for GitLab.com [in Kibana](https://log.gprd.gitlab.net/goto/d060337c017723084c6d97e09e591fc6).
 
 ## Cleaning up
 
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.