We are announcing a number of implementation updates related to OEP-17: Feature Toggles, which covers how to implement toggles, document toggles, and report on toggles for discovery and removal.
Implement and Document Toggles
Use our toggles library throughout the Open edX codebase, in any Independently Deployable Application (IDA) (e.g. the LMS, Studio, Discovery, etc.).
How do I learn more about toggles and how to annotate them?
- See how to choose the right toggle type and class.
- See how to document your toggles with annotations, which includes special considerations for Legacy toggles.
- Have no fear. Linting should already be in place via edx-lint for your annotations.
Can I also document non-toggle Django settings?
You bet!
- See how to document other Django settings.
- To publish to readthedocs, follow similar steps from the first section of the how-to for enabling toggles reporting for your IDA.
Have we started documenting toggles (and settings)?
Yes we have. Also, if you haven’t yet read about it, see our blog post on the Toggles and Settings Doc-a-thon 2021.
Reporting Capabilities
The toggles reporting capabilities are also available for all IDAs, but there is some minor work to do to expose the capabilities in IDAs outside of edx-platform.
Here are the feature toggle reporting capabilities that could be made available for your favorite IDA
-
Discover and understand how to use your IDA’s feature toggles through generated documentation.
-
Discover and see the current state of your IDA’s waffle flags, switches, and boolean Django settings in Production using a toggle state endpoint.
- See the edx-platform toggle state endpoint at
/api/toggles/v0/state/:
- See the edx-platform toggle state endpoint at
-
Discover , track , and remove your IDA’s outdated toggles by seeing a consolidated view of annotations and state combined across multiple environments in a single spreadsheet.
- Example Toggle State Reports spreadsheet:
-
Note: Although parts of this capability are internal to edX.org, its documentation is publicly available.
How do I get these toggle reporting capabilities for my favorite IDA?
If you want one or any of the above capabilities for your IDA, just follow the simple steps in the how-to for enabling toggles reporting for your IDA.
That’s really cool. Can I write new types of annotations and extract to readthedocs?
With a little elbow grease.
How did this all come to be?
Thanks to all involved in the blended project: [BD-21] Toggles/Settings Documentation, and a special thanks to @regis. These updates were built upon former work from the Arch-BOM squad.
- See a summary of the BD-21 work.