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 be added in the merge request removing the feature flags.

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 feature flag by 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.

As an example, if you were to ship the backend half of a feature behind a flag, you'd want to explicitly disable that flag until the frontend half is also ready to be shipped. You can do this via Chatops:

/chatops run feature set some_feature 0

Note that you can do this at any time, even before the merge request using the flag has been merged!

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 param 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.

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)