Commit 283e670e authored by Mark Chao's avatar Mark Chao

[Doc] Clarify feature flag changelog types

Expand changelog for feature flag guide
parent a2d53b3f
......@@ -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.
......
......@@ -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.
......
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