diff options
Diffstat (limited to 'doc/development/feature_flags')
| -rw-r--r-- | doc/development/feature_flags/controls.md | 20 | ||||
| -rw-r--r-- | doc/development/feature_flags/development.md | 49 | ||||
| -rw-r--r-- | doc/development/feature_flags/index.md | 31 | ||||
| -rw-r--r-- | doc/development/feature_flags/process.md | 27 |
4 files changed, 82 insertions, 45 deletions
diff --git a/doc/development/feature_flags/controls.md b/doc/development/feature_flags/controls.md index df737912c00..7551199aa58 100644 --- a/doc/development/feature_flags/controls.md +++ b/doc/development/feature_flags/controls.md @@ -34,7 +34,7 @@ _before_ the code is being deployed. This allows you to separate rolling out a feature from a deploy, making it easier to measure the impact of both separately. -GitLab's feature library (using +The GitLab feature library (using [Flipper](https://github.com/jnunemaker/flipper), and covered in the [Feature Flags process](process.md) guide) supports rolling out changes to a percentage of time to users. This in turn can be controlled using [GitLab Chatops](../../ci/chatops/README.md). @@ -50,7 +50,7 @@ change feature flags or you do not [have access](#access). ### Enabling a feature for preproduction testing -As a first step in a feature rollout, you should enable the feature on <https://staging.gitlab.com> +As a first step in a feature rollout, you should enable the feature on <https://about.staging.gitlab.com> and <https://dev.gitlab.org>. These two environments have different scopes. @@ -228,21 +228,29 @@ existing gates (e.g. `--group=gitlab-org`) in the above processes. ### Feature flag change logging -Any feature flag change that affects GitLab.com (production) will -automatically be logged in an issue. +#### Chatops level + +Any feature flag change that affects GitLab.com (production) via [Chatops](https://gitlab.com/gitlab-com/chatops) +is automatically logged in an issue. The issue is created in the [gl-infra/feature-flag-log](https://gitlab.com/gitlab-com/gl-infra/feature-flag-log/-/issues?scope=all&utf8=%E2%9C%93&state=closed) project, and it will at minimum log the Slack handle of person enabling a feature flag, the time, and the name of the flag being changed. -The issue is then also posted to GitLab's internal +The issue is then also posted to the GitLab internal [Grafana dashboard](https://dashboards.gitlab.net/) as an annotation marker to make the change even more visible. Changes to the issue format can be submitted in the [Chatops project](https://gitlab.com/gitlab-com/chatops). +#### Instance level + +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). + ## Cleaning up A feature flag should be removed as soon as it is no longer needed. Each additional @@ -266,7 +274,7 @@ To remove a feature flag: ### Cleanup ChatOps -When a feature gate has been removed from the code base, the feature +When a feature gate has been removed from the codebase, the feature record still exists in the database that the flag was deployed too. The record can be deleted once the MR is deployed to each environment: diff --git a/doc/development/feature_flags/development.md b/doc/development/feature_flags/development.md index 2855662e1db..7c5333c9aa6 100644 --- a/doc/development/feature_flags/development.md +++ b/doc/development/feature_flags/development.md @@ -17,12 +17,18 @@ request removing the feature flag or the merge request where the default value o the feature flag is set to enabled. If the feature contains any database migrations, it *should* include a changelog entry for the database changes. -CAUTION: **Caution:** +WARNING: All newly-introduced feature flags should be [disabled by default](process.md#feature-flags-in-gitlab-development). -NOTE: **Note:** +NOTE: This document is the subject of continued work as part of an epic to [improve internal usage of Feature Flags](https://gitlab.com/groups/gitlab-org/-/epics/3551). Raise any suggestions as new issues and attach them to the epic. +## Risk of a broken master (main) branch + +Feature flags **must** be used in the MR that introduces them. Not doing so causes a +[broken master](https://about.gitlab.com/handbook/engineering/workflow/#broken-master) scenario due +to the `rspec:feature-flags` job that only runs on the `master` branch. + ## Types of feature flags Choose a feature flag type that matches the expected usage. @@ -40,11 +46,11 @@ This is the default type used when calling `Feature.enabled?`. ### `ops` type `ops` feature flags are long-lived feature flags that control operational aspects -of GitLab's behavior. For example, feature flags that disable features that might +of GitLab product behavior. For example, feature flags that disable features that might have a performance impact, like special Sidekiq worker behavior. `ops` feature flags likely do not have rollout issues, as it is hard to -predict when they will be enabled or disabled. +predict when they are enabled or disabled. To use `ops` feature flags, you must append `type: :ops` to `Feature.enabled?` invocations: @@ -88,9 +94,9 @@ Each feature flag is defined in a separate YAML file consisting of a number of f | `default_enabled` | yes | The default state of the feature flag that is strictly validated, with `default_enabled:` passed as an argument. | | `introduced_by_url` | no | The URL to the Merge Request that introduced the feature flag. | | `rollout_issue_url` | no | The URL to the Issue covering the feature flag rollout. | -| `group` | no | The [group](https://about.gitlab.com/handbook/product/product-categories/#devops-stages) that owns the feature flag. | +| `group` | no | The [group](https://about.gitlab.com/handbook/product/categories/#devops-stages) that owns the feature flag. | -TIP: **Tip:** +NOTE: All validations are skipped when running in `RAILS_ENV=production`. ## Create a new feature flag @@ -125,7 +131,7 @@ type: development default_enabled: false ``` -TIP: **Tip:** +NOTE: To create a feature flag that is only used in EE, add the `--ee` flag: `bin/feature-flag --ee` ## Delete a feature flag @@ -172,6 +178,29 @@ if Feature.disabled?(:my_feature_flag, project, default_enabled: true) end ``` +If not specified, `default_enabled` is `false`. + +To force reading the `default_enabled` value from the relative YAML definition file, use +`default_enabled: :yaml`: + +```ruby +if Feature.enabled?(:feature_flag, project, default_enabled: :yaml) + # execute code if feature flag is enabled +end +``` + +```ruby +if Feature.disabled?(:feature_flag, project, default_enabled: :yaml) + # execute code if feature flag is disabled +end +``` + +This allows to use the same feature flag check across various parts of the codebase and +maintain the status of `default_enabled` in the YAML definition file which is the SSOT. + +If `default_enabled: :yaml` is used, a YAML definition is expected or an error is raised +in development or test environment, while returning `false` on production. + If not specified, the default feature flag type for `Feature.enabled?` and `Feature.disabled?` is `type: development`. For all other feature flag types, you must specify the `type:`: @@ -187,7 +216,7 @@ if Feature.disabled?(:my_feature_flag, project, type: :ops) end ``` -DANGER: **Warning:** +WARNING: Don't use feature flags at application load time. For example, using the `Feature` class in `config/initializers/*` or at the class level could cause an unexpected error. This error occurs because a database that a feature flag adapter might depend on doesn't exist at load time @@ -497,10 +526,6 @@ is persisted. Make sure behavior under feature flag doesn't go untested in some non-specific contexts. -See the -[testing guide](../testing_guide/best_practices.md#feature-flags-in-tests) -for information and examples on how to stub feature flags in tests. - ### `stub_feature_flags: false` This disables a memory-stubbed flipper, and uses `Flipper::Adapters::ActiveRecord` diff --git a/doc/development/feature_flags/index.md b/doc/development/feature_flags/index.md index a867bcf792a..270e07ed755 100644 --- a/doc/development/feature_flags/index.md +++ b/doc/development/feature_flags/index.md @@ -6,18 +6,43 @@ info: "See the Technical Writers assigned to Development Guidelines: https://abo # Feature flags in development of GitLab +## When to use feature flags + +Starting with GitLab 11.4, developers are required to use feature flags for +non-trivial changes. Such changes include: + +- New features (e.g. a new merge request widget, epics, etc). +- Complex performance improvements that may require additional testing in + production, such as rewriting complex queries. +- Invasive changes to the user interface, such as a new navigation bar or the + removal of a sidebar. +- Adding support for importing projects from a third-party service. +- Risk of data loss + +In all cases, those working on the changes can best decide if a feature flag is +necessary. For example, changing the color of a button doesn't need a feature +flag, while changing the navigation bar definitely needs one. In case you are +uncertain if a feature flag is necessary, simply ask about this in the merge +request, and those reviewing the changes will likely provide you with an answer. + +When using a feature flag for UI elements, make sure to _also_ use a feature +flag for the underlying backend code, if there is any. This ensures there is +absolutely no way to use the feature until it is enabled. + +## How to use Feature Flags + Feature flags can be used to gradually deploy changes, regardless of whether they are new features or performance improvements. By using feature flags, you can determine the impact of GitLab-directed changes, while still being able to disable those changes without having to revert an entire release. -Before using feature flags for GitLab's development, review the following development guides: +Before using feature flags for GitLab development, review the following development guides: -NOTE: **Note:** +NOTE: The feature flags used by GitLab to deploy its own features **are not** the same as the [feature flags offered as part of the product](../../operations/feature_flags.md). -For an overview about starting with feature flags in GitLab's development, +For an overview about starting with feature flags in GitLab development, use this [training template](https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/master/.gitlab/issue_templates/feature-flag-training.md). Development guides: diff --git a/doc/development/feature_flags/process.md b/doc/development/feature_flags/process.md index b282424f59a..2e3680bb103 100644 --- a/doc/development/feature_flags/process.md +++ b/doc/development/feature_flags/process.md @@ -32,7 +32,8 @@ should be leveraged: requests, you can use the following workflow: 1. [Create a new feature flag](development.md#create-a-new-feature-flag) - which is **off** by default, in the first merge request. + which is **off** by default, in the first merge request which uses the flag. + Flags [should not be added separately](development.md#risk-of-a-broken-master-main-branch). 1. Submit incremental changes via one or more merge requests, ensuring that any new code added can only be reached if the feature flag is **on**. You can keep the feature flag enabled on your local GDK during development. @@ -52,28 +53,6 @@ problems, such as outages. Please also read the [development guide for feature flags](development.md). -### When to use feature flags - -Starting with GitLab 11.4, developers are required to use feature flags for -non-trivial changes. Such changes include: - -- New features (e.g. a new merge request widget, epics, etc). -- Complex performance improvements that may require additional testing in - production, such as rewriting complex queries. -- Invasive changes to the user interface, such as a new navigation bar or the - removal of a sidebar. -- Adding support for importing projects from a third-party service. - -In all cases, those working on the changes can best decide if a feature flag is -necessary. For example, changing the color of a button doesn't need a feature -flag, while changing the navigation bar definitely needs one. In case you are -uncertain if a feature flag is necessary, simply ask about this in the merge -request, and those reviewing the changes will likely provide you with an answer. - -When using a feature flag for UI elements, make sure to _also_ use a feature -flag for the underlying backend code, if there is any. This ensures there is -absolutely no way to use the feature until it is enabled. - ### Including a feature behind feature flag in the final release In order to build a final release and present the feature for self-managed @@ -91,7 +70,7 @@ account for unforeseen problems. Feature flags must be [documented according to their state (enabled/disabled)](../documentation/feature_flags.md), and when the state changes, docs **must** be updated accordingly. -NOTE: **Note:** +NOTE: Take into consideration that such action can make the feature available on GitLab.com shortly after the change to the feature flag is merged. |