diff options
Diffstat (limited to 'doc/development/feature_flags/index.md')
| -rw-r--r-- | doc/development/feature_flags/index.md | 37 |
1 files changed, 36 insertions, 1 deletions
diff --git a/doc/development/feature_flags/index.md b/doc/development/feature_flags/index.md index d9eb29a7b7f..8c0f7faab28 100644 --- a/doc/development/feature_flags/index.md +++ b/doc/development/feature_flags/index.md @@ -199,7 +199,7 @@ Only feature flags that have a YAML definition file can be used when running the ```shell $ bin/feature-flag my_feature_flag ->> Specify the group introducing the feature flag, like `group::apm`: +>> Specify the group introducing the feature flag, like `group::project management`: ?> group::application performance >> URL of the MR introducing the feature flag (enter to skip): @@ -231,6 +231,20 @@ the feature flag is set to enabled. If the feature contains any database migrati NOTE: To create a feature flag that is only used in EE, add the `--ee` flag: `bin/feature-flag --ee` +### Naming new flags + +When choosing a name for a new feature flag, consider the following guidelines: + +- A long, descriptive name is better than a short but confusing one. +- Write the name in snake case (`my_cool_feature_flag`). +- Avoid using `disable` in the name to avoid having to think (or [document](../documentation/feature_flags.md)) + with double negatives. Consider starting the name with `hide_`, `remove_`, or `disallow_`. + + In software engineering this problem is known as + ["negative names for boolean variables"](https://www.serendipidata.com/posts/naming-guidelines-for-boolean-variables). + But we can't forbid negative words altogether, to be able to introduce flags as + [disabled by default](#feature-flags-in-gitlab-development), use them to remove a feature by moving it behind a flag, or to [selectively disable a flag by actor](controls.md#selectively-disable-by-actor). + ### Risk of a broken master (main) branch WARNING: @@ -543,6 +557,8 @@ to ensure the feature works properly. If automated tests are not included for bo with the untested code path should be manually tested before deployment to production. When using the testing environment, all feature flags are enabled by default. +Flags can be disabled by default in the [`spec/spec_helper.rb` file](https://gitlab.com/gitlab-org/gitlab/-/blob/b61fba42eea2cf5bb1ca64e80c067a07ed5d1921/spec/spec_helper.rb#L274). +Please add a comment inline to explain why the flag needs to be disabled. You can also attach the issue URL for reference if possible. WARNING: This does not apply to end-to-end (QA) tests, which [do not enable feature flags by default](#end-to-end-qa-tests). There is a different [process for using feature flags in end-to-end tests](../testing_guide/end_to_end/feature_flags.md). @@ -557,6 +573,25 @@ stub_feature_flags(ci_live_trace: false) Feature.enabled?(:ci_live_trace) # => false ``` +A common pattern of testing both paths looks like: + +```ruby +it 'ci_live_trace works' do + # tests assuming ci_live_trace is enabled in tests by default + Feature.enabled?(:ci_live_trace) # => true +end + +context 'when ci_live_trace is disabled' do + before do + stub_feature_flags(ci_live_trace: false) + end + + it 'ci_live_trace does not work' do + Feature.enabled?(:ci_live_trace) # => false + end +end +``` + If you wish to set up a test where a feature flag is enabled only for some actors and not others, you can specify this in options passed to the helper. For example, to enable the `ci_live_trace` |