Table of Contents
Rules of thumb
- Use Waffle to add flexible and temporary feature flags used to roll-out a feature.
- For more permanent feature flags, prefer model-based configuration using config models.
- 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.
- When removing a model-based config field, remove use of it from the code before removing the field with a migration.
...
- CourseWaffleFlag: An edx-platform class that supports Course Overrides of Waffle Flags (in addition to caching and name-spacing). Use this for all waffle flags inside a course. (See Waffle Utils.)
- Waffle (Flag): Refers to the out of the box Waffle capabilities.
WaffleFlag: An edx-platform class that supports caching and name-spacing. Use this for all waffle flags outside a course. (See Waffle Utils.)
Waffle Utils: A set of Waffle related utilities, including CourseWaffleFlag and WaffleFlag.
| Early Beta | Late Beta (more optional) | Stable | Complete |
|---|---|---|---|
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.
...
- For a long-lived feature flag, make super sure that the team wants to use a feature flag. Ask many people for their opinions, and explore other options first if they’re available.
- Add your feature flag to the doc page at https://openedx.atlassian.net/wiki/display/EdxOps/edX + Feature + Flags, along with description, notes, contact, etc. If prior discussions about the flag are on a JIRA ticket, link that in as well!
- Modify lms/envs/common.py (or cms/envs/common.py) to include your feature flag (in ALL_CAPS), along with its default value.
- At the points where you’ll be “gating” access, get the boolean value like this:
settings.FEATURES.get('ENABLE_TEAMS', False). This will check for the feature flag in common.py and use its value if present, or default to false.
...