Page Comparison

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.

...

• If using a flag to have a staged rollout of a feature:
  • Use Waffle.
  • Work to remove the flag ASAP after full rollout.  Track this with a JIRA ticket.
  • Be sure that all entry points are covered by a flag check.
  • Run tests in 2 ways:
    • With all flags set as expected to be in the next release
    • With all flags set to their eventual end state
• If using a flag to enable selective functionality:
  • Minimize dependence on code that is covered by the feature flag. Modularity is king.
  • Make sure all entry points are masked by a feature flag check
  • Run tests both with and without the flag

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.

...

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:

• For Waffle, see the waffle docs for unit testing.  
• In edx-platform, if you are using the WaffleFlag or CourseWaffleFlag, you can instead use the override_waffle_flag decorator implemented in this testutils.py file.

Bok-choy Testing:

• Bok-choy tests cannot use the decorator because the server is separate from the test code.
• To override in the URL, see the External Test Suites section of the Waffle documentation. Read the following important details as well.
  • In order to override a flag, it must first exist in the database.
    • In edx-platform, you can temporarily create a record in common/test/db_fixtures/waffle_flags.json that will be loaded directly into mysql for bok-choy tests only.  Note that you can default the flag on or off depending on your needs.
    • Other teams temporarily create a migration which will create the flag in all environments, including Production. 
  • Note: In edx-platform, the WAFFLE_OVERRIDE setting is already taken care of in bok-choy to enable this type of URL override.

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

...