Rules of thumb

  1. Use Waffle to add flexible and temporary feature flags used to roll-out a feature.
  2. For more permanent feature flags, prefer model-based configuration using config models.
    1. Note that the same config model is used for edx.org and white label sites.  If you need a white label aware setting, then don't use a config model.
  3. When removing a model-based config field, remove use of it from the code before removing the field with a migration.

How feature flags are currently used (simple case):

Why are feature flags used?

What alternatives are there?

Feature flag best practices:

Using Waffle

Staged Rollout

You can use Waffle and the edx-platform Waffle Utils to have a staged rollout of a feature using a temporary flag. Typically, the sooner you can reach completion, the better.  Not all stages or capabilities are required.

Definitions:


Early BetaLate Beta (more optional)StableComplete

Use a Waffle Flag to beta test with individual users in Production, both internal and partners. Implement with CourseWaffleFlag or WaffleFlag to enable future rollout capabilities.

Use Waffle Utils Course Override capabilities to add one or more courses to the beta test.

Use Waffle to turn the feature on for everyone in an environment (e.g. edx.org).

Other environments (e.g. edge.edx.org) may lag (or be ahead).

Change the default for the feature to "on" for environments that aren't yet using the flag (e.g. some devstacks, sandboxes, Open edX releases*).

Waffle Utils Course Override could be used to turn the feature off for a course, but this will delay completion, so use sparingly.

The feature has been rolled out to all edX environments. The flag and legacy code should all be removed.

If there is a strong reason to enable the Open edX community to have the same rollout capabilities, consider delaying clean-up until after the next Open edX release.

If you absolutely must support the feature both on and off, transition the Waffle Flag to a more permanent setting or ConfigModel.

Open edX releases*: The aim is for these waffle flags to be short-lived.  However, due to timing or complicated rollouts, you may need to consider how to handle the flag across different Open edX releases as described in the table above.

Testing Waffle Flags

Python Unit Tests:

Bok-choy Testing:

Current edX Feature Flag usage, a step-by-step guide:

Reference: http://martinfowler.com/bliki/FeatureToggle.html