diff options
Diffstat (limited to 'doc/development/feature_flags/index.md')
| -rw-r--r-- | doc/development/feature_flags/index.md | 14 |
1 files changed, 8 insertions, 6 deletions
diff --git a/doc/development/feature_flags/index.md b/doc/development/feature_flags/index.md index 7370697b082..87d2da016d6 100644 --- a/doc/development/feature_flags/index.md +++ b/doc/development/feature_flags/index.md @@ -35,7 +35,7 @@ should be leveraged: the status of a feature behind the feature flag in the documentation and with other stakeholders. The issue description should be updated with the feature flag name and whether it is defaulted on or off as soon it is evident that a feature flag is needed. -- Merge requests that introduce a feature flag, update its state, or remove them +- Merge requests that introduce a feature flag, update its state, or remove the existing feature flag because a feature is deemed stable must have the ~"feature flag" label assigned. @@ -83,7 +83,7 @@ used for deploying unfinished code to production. Most feature flags used at GitLab are the `development` type. A `development` feature flag must have a rollout issue -created from the [Feature Flag Roll Out template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/issue_templates/Feature%20Flag%20Roll%20Out.md). +created from the [Feature flag Roll Out template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/issue_templates/Feature%20Flag%20Roll%20Out.md). The format for `development` feature flags is `Feature.<state>(:<dev_flag_name>)`. To enable and disable them, run on the GitLab Rails console: @@ -252,7 +252,7 @@ deleting feature flags. ## Develop with a feature flag -There are two main ways of using Feature Flags in the GitLab codebase: +There are two main ways of using feature flags in the GitLab codebase: - [Backend code (Rails)](#backend) - [Frontend code (VueJS)](#frontend) @@ -505,9 +505,12 @@ Feature.remove(:feature_flag_name) ## Changelog +We want to avoid introducing a changelog when features are not accessible by an end-user either directly (example: ability to use the feature) or indirectly (examples: ability to take advantage of background jobs, performance improvements, or database migration updates). + +- Database migrations are always accessible by an end-user indirectly, as self-managed customers need to be aware of database changes before upgrading. For this reason, they **should** have a changelog entry. - 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](../changelog.md). +- Any change behind a feature flag that is **enabled** by default **should** have a changelog entry. +- Changing the feature flag itself (flag removal, default-on setting) **should** have [a changelog entry](../changelog.md). Use the flowchart to determine the changelog entry type. ```mermaid @@ -519,7 +522,6 @@ Feature.remove(:feature_flag_name) A -->|no changelog| D ``` -- Any change behind a feature flag that is **enabled** by default **should** have a changelog entry. - The changelog for a feature flag should describe the feature and not the flag, unless a default on feature flag is removed keeping the new code (`other` in the flowchart above). - A feature flag can also be used for rolling out a bug fix or a maintenance work. In this scenario, the changelog |