There are three ways to report on feature toggles in an Independently Deployable Application (IDA).
Generated documentation based on annotated feature toggles.
REST endpoint providing the current state of feature toggles at a given time from a given environment.
A generated spreadsheet combining data from the static feature toggle annotations and the toggle state data from the Toggles State Endpoint.
You can extract your toggle annotations from code in order to create documentation on Readthedocs for your IDA.
Here are some helpful examples and resources:
Steps required (2-4 hours):
featurestoggles.rst and configuration for the
featuretoggles Sphinx extension from edx-platform.
Here is a search for featuretoggles in edx-platform.
You can follow similar steps to use the settings Sphinx extension to publish non-boolean non-toggle setting annotations as well.
Add a REST endpoint to your IDA that provides the current state of all your toggles, including all
waffle toggles and all boolean Django Settings. This endpoint will be available from all environments, including Production.
Here is an example from edx-platform:
https://courses.edx.org/api/toggles/v0/state/ (requires Staff access)
Steps required (2-4 hours):
Add a view wrapping
ToggleStateReport().as_dict() for your new toggle state REST endpoint:
edx-toggles in the
base.in requirements file (if not already there).
Create a view using the ToggleStateReport class to implement the REST endpoint.
Our convention is to use the path
Protect the view as a appropriate, potentially limiting to Staff access.
See an example toggles state endpoint view in edx-platform.
For most IDAs, just replace
report = CourseOverrideToggleStateReport().as_dict()with
report = ToggleStateReport().as_dict()from the example code.
Add the view to a
urls.py like in this example urls.py in edx-platform.
(Optional) If your IDA has custom toggle types, you can subclass and override the reporting methods as was done in the edx-platform example toggles state endpoint view.
Much of this section is specific to edX.org, including private links, but the general approach and some of the scripts are available to the wider Open edX community.
Add an IDA to the spreadsheet which combines data from the static feature toggle annotations and the toggle state data.
See the current Toggle State Reports Spreadsheet (private to edX.org).
Implement the Toggles State Endpoint in your IDA.
Steps required (1 hour):
This section describes how the Toggle State Reports Spreadsheet is generated. This information is not required knowledge for setting up a new IDA.
The steps to collect annotations are automated through a Jenkins job:
groovy job specification in
Once the job is done, the annotations data is pushed to an S3 bucket: script to push data to s3 bucket
The job creates files with names like
<ida_name>-annotations.yml. The feature toggle report generator will key off the
ida_name in the filename in order to be able to link this data to the toggle state data collected.
Toggle state will be gathered from the new Toggles State Endpoint.
Collection of state data is automated through a jenkins job.
The annotation data and toggle state data dump should be stored in s3 buckets. The automated publish-feature-toggle-report job (in groovy job specification) pulls the data from s3 buckets and calls feature_toggle_report_generator.py to process the data and output it as a csv file.
As long as the data is structured correctly (specified in README), no action should be necessary for a new IDA.
The toggle csv reports are retained as artifacts in the Jenkins job: publish-feature-toggle-report.
The csv reports are published to a private Google Sheet. See Toggle State Reports Spreadsheet (private to edX.org).