diff options
Diffstat (limited to 'doc/development/feature_flags')
-rw-r--r-- | doc/development/feature_flags/controls.md | 14 | ||||
-rw-r--r-- | doc/development/feature_flags/index.md | 14 |
2 files changed, 16 insertions, 12 deletions
diff --git a/doc/development/feature_flags/controls.md b/doc/development/feature_flags/controls.md index 3adf5248b8d..d341cb3f1ba 100644 --- a/doc/development/feature_flags/controls.md +++ b/doc/development/feature_flags/controls.md @@ -40,7 +40,7 @@ easier to measure the impact of both separately. The GitLab feature library (using [Flipper](https://github.com/jnunemaker/flipper), and covered in the -[Feature Flags process](https://about.gitlab.com/handbook/product-development-flow/feature-flag-lifecycle/) guide) supports rolling out changes to a percentage of +[Feature flags process](https://about.gitlab.com/handbook/product-development-flow/feature-flag-lifecycle/) guide) supports rolling out changes to a percentage of time to users. This in turn can be controlled using [GitLab ChatOps](../../ci/chatops/index.md). For an up to date list of feature flag commands please see @@ -84,6 +84,8 @@ When a feature has successfully been environment and verified as safe and working, you can roll out the change to GitLab.com (production). +If a feature is [deprecated](../../update/deprecations.md), do not enable the flag. + #### Communicate the change Some feature flag changes on GitLab.com should be communicated with @@ -113,13 +115,13 @@ incidents or in-progress change issues, for example: 2021-06-29 Canary deployment failing QA tests ``` -Before enabling a feature flag, verify that you are not violating any [Production Change Lock periods](https://about.gitlab.com/handbook/engineering/infrastructure/change-management/#production-change-lock-pcl) and are in compliance with the [Feature Flags and the Change Management Process](https://about.gitlab.com/handbook/engineering/infrastructure/change-management/#feature-flags-and-the-change-management-process). +Before enabling a feature flag, verify that you are not violating any [Production Change Lock periods](https://about.gitlab.com/handbook/engineering/infrastructure/change-management/#production-change-lock-pcl) and are in compliance with the [Feature flags and the Change Management Process](https://about.gitlab.com/handbook/engineering/infrastructure/change-management/#feature-flags-and-the-change-management-process). The following `/chatops` commands should be performed in the Slack `#production` channel. When you begin to enable the feature, please link to the relevant -Feature Flag Rollout Issue within a Slack thread of the first `/chatops` +feature flag rollout issue within a Slack thread of the first `/chatops` command you make so people can understand the change if they need to. To enable a feature for 25% of the time, run the following in Slack: @@ -356,7 +358,7 @@ After turning on the feature flag, you need to [monitor the relevant graphs](htt In this illustration, you can see that the Apdex score started to decline after the feature flag was enabled at `09:46`. The feature flag was then deactivated at `10:31`, and the service returned to the original value: -![Feature Flag Metrics](../img/feature-flag-metrics.png) +![Feature flag metrics](../img/feature-flag-metrics.png) ### Feature flag change logging @@ -408,8 +410,8 @@ take one of the following actions: To remove a feature flag, open **one merge request** to make the changes. In the MR: 1. Add the ~"feature flag" label so release managers are aware of the removal. -1. If the merge request has to be picked into a stable branch, add the - appropriate `~"Pick into X.Y"` label, for example `~"Pick into 13.0"`. +1. If the merge request has to be backported into the current version, follow the + [patch release runbook](https://gitlab.com/gitlab-org/release/docs/-/blob/master/general/patch/engineers.md) process. See [the feature flag process](https://about.gitlab.com/handbook/product-development-flow/feature-flag-lifecycle/#including-a-feature-behind-feature-flag-in-the-final-release) for further details. 1. Remove all references to the feature flag from the codebase, including tests. 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 |