gitlab-org--gitlab-foss/doc/development/feature_flags/development.md

Developing with feature flags

In general, it's better to have a group- or user-based gate, and you should prefer it over the use of percentage gates. This would make debugging easier, as you filter for example logs and errors based on actors too. Furthermore, this allows for enabling for the gitlab-org or gitlab-com group first, while the rest of the users aren't impacted.

# Good
Feature.enabled?(:feature_flag, project)

# Avoid, if possible
Feature.enabled?(:feature_flag)

To use feature gates based on actors, the model needs to respond to flipper_id. For example, to enable for the Foo model:

class Foo < ActiveRecord::Base
  include FeatureGate
end

Features that are developed and are intended to be merged behind a feature flag should not include a changelog entry. The entry should either be added in the merge request removing the feature flag or the merge request where the default value of the feature flag is set to true. If the feature contains any DB migration it should include a changelog entry for DB changes.

In the rare case that you need the feature flag to be on automatically, use default_enabled: true when checking:

Feature.enabled?(:feature_flag, project, default_enabled: true)

The Project#feature_available?, Namespace#feature_available? (EE), and License.feature_available? (EE) methods all implicitly check for a by default enabled feature flag with the same name as the provided argument.

For example if a feature is license-gated, there's no need to add an additional explicit feature flag check since the flag will be checked as part of the License.feature_available? call. Similarly, there's no need to "clean up" a feature flag once the feature has reached general availability.

You'd still want to use an explicit Feature.enabled? check if your new feature isn't gated by a License or Plan.

An important side-effect of the implicit feature flags mentioned above is that unless the feature is explicitly disabled or limited to a percentage of users, the feature flag check will default to true.

This is relevant when developing the feature using several smaller merge requests, or when the feature is considered to be an alpha or beta, and should not be available by default.

As an example, if you were to ship the frontend half of a feature without the backend, you'd want to disable the feature entirely until the backend half is also ready to be shipped. To make sure this feature is disabled for both GitLab.com and self-managed instances, you should use the Namespace#alpha_feature_available? or Namespace#beta_feature_available? method, according to our definitions. This ensures the feature is disabled unless the feature flag is explicitly enabled.

Feature groups

Starting from GitLab 9.4 we support feature groups via Flipper groups.

Feature groups must be defined statically in lib/feature.rb (in the .register_feature_groups method), but their implementation can obviously be dynamic (querying the DB etc.).

Once defined in lib/feature.rb, you will be able to activate a feature for a given feature group via the feature_group parameter of the features API

Frontend

For frontend code you can use the method push_frontend_feature_flag, which is available to all controllers that inherit from ApplicationController. Using this method you can expose the state of a feature flag as follows:

before_action do
  push_frontend_feature_flag(:vim_bindings)
end

def index
  # ...
end

def edit
  # ...
end

You can then check for the state of the feature flag in JavaScript as follows:

if ( gon.features.vimBindings ) {
  // ...
}

The name of the feature flag in JavaScript will always be camelCased, meaning that checking for gon.features.vim_bindings would not work.

See the Vue guide for details about how to access feature flags in a Vue component.

Specs

In the test environment Feature.enabled? is stubbed to always respond to true, so we make sure behavior under feature flag doesn't go untested in some non-specific contexts.

Whenever a feature flag is present, make sure to test both states of the feature flag.

See the testing guide for information and examples on how to stub feature flags in tests.

Enabling a feature flag (in development)

In the rails console (rails c), enter the following command to enable your feature flag

Feature.enable(:feature_flag_name)

Similarly, the following command will disable a feature flag:

Feature.disable(:feature_flag_name)