use new, shorter names for feature toggle annotations (openedx#20202)

alangsto · Apr 12, 2019 · 05a682f · 05a682f
1 parent 81721dc
commit 05a682f
Show file tree

Hide file tree

Showing 6 changed files with 168 additions and 102 deletions.
diff --git a/cms/envs/common.py b/cms/envs/common.py
@@ -176,6 +176,9 @@
     # in sync with the ones in lms/envs/common.py
     'ENABLE_DISCUSSION_SERVICE': True,
     'ENABLE_TEXTBOOK': True,
+
+    # .. documented_elsewhere: true
+    # .. documented_elsewhere_name: ENABLE_STUDENT_NOTES
     'ENABLE_STUDENT_NOTES': True,
 
     # DO NOT SET TO True IN THIS FILE

diff --git a/doc.rst.j2 b/doc.rst.j2
@@ -0,0 +1,29 @@
+###############
+Feature Toggles
+###############
+
+These are all of our well-documented feature toggles!
+
+{% for group in groups %}
+{{ group.toggle_name }}
+{{ '*'*(group.toggle_name|length) }}
+
+{{ group.toggle_description }}
+
+* Type: {{ group.toggle_type[0] }}
+* Status: {{ group.toggle_status }}
+* Use cases: {{ group.toggle_use_cases|join(", ") }}
+{% if group.toggle_warnings != 'None' -%}
+* Warnings: {{ group.toggle_warnings }}
+{% endif -%}
+{% if group.toggle_expiration_date != 'None' -%}
+* Expiration date: {{ group.toggle_expiration_date }}
+{% endif -%}
+* Category: {{ group.toggle_category }}
+{% if group.toggle_tickets != 'None' -%}
+* Tickets: {{ group.toggle_tickets }}
+{% endif -%}
+* Default: {{ group.toggle_default }}
+* Defined at: {{ group.filename }}:{{ group.line_number }}
+
+{% endfor %}
diff --git a/lms/djangoapps/bulk_email/models.py b/lms/djangoapps/bulk_email/models.py
@@ -451,6 +451,17 @@ def __unicode__(self):
         return u"Course '{}': Instructor Email {}Enabled".format(text_type(self.course_id), not_en)
 
 
+# .. toggle_name: require_course_email_auth
+# .. toggle_type: ConfigurationModel
+# .. toggle_default: True (enabled)
+# .. toggle_description: If the flag is enabled, course-specific authorization is required, and the course_id is either not provided or not authorixed, the feature is not available.
+# .. toggle_category: bulk email
+# .. toggle_use_cases: open_edx
+# .. toggle_creation_date: 2016-05-05
+# .. toggle_expiration_date: None
+# .. toggle_warnings: None
+# .. toggle_tickets: None
+# .. toggle_status: supported
 class BulkEmailFlag(ConfigurationModel):
     """
     Enables site-wide configuration for the bulk_email feature.

diff --git a/lms/djangoapps/experiments/utils.py b/lms/djangoapps/experiments/utils.py
@@ -26,52 +26,52 @@
 # TODO: clean up as part of REVEM-199 (START)
 experiments_namespace = WaffleFlagNamespace(name=u'experiments')
 
-# .. feature_toggle_name: experiments.add_programs
-# .. feature_toggle_type: flag
-# .. feature_toggle_default: False
-# .. feature_toggle_description: Toggle for adding the current course's program information to user metadata
-# .. feature_toggle_category: experiments
-# .. feature_toggle_use_cases: monitored_rollout
-# .. feature_toggle_creation_date: 2019-2-25
-# .. feature_toggle_expiration_date: None
-# .. feature_toggle_warnings: None
-# .. feature_toggle_tickets: REVEM-63, REVEM-198
-# .. feature_toggle_status: supported
+# .. toggle_name: experiments.add_programs
+# .. toggle_type: feature_flag
+# .. toggle_default: False
+# .. toggle_description: Toggle for adding the current course's program information to user metadata
+# .. toggle_category: experiments
+# .. toggle_use_cases: monitored_rollout
+# .. toggle_creation_date: 2019-2-25
+# .. toggle_expiration_date: None
+# .. toggle_warnings: None
+# .. toggle_tickets: REVEM-63, REVEM-198
+# .. toggle_status: supported
 PROGRAM_INFO_FLAG = WaffleFlag(
     waffle_namespace=experiments_namespace,
     flag_name=u'add_programs',
     flag_undefined_default=False
 )
 
-# .. feature_toggle_name: experiments.add_program_price
-# .. feature_toggle_type: flag
-# .. feature_toggle_default: False
-# .. feature_toggle_description: Toggle for adding the current course's program price and sku information to user
+# .. toggle_name: experiments.add_program_price
+# .. toggle_type: feature_flag
+# .. toggle_default: False
+# .. toggle_description: Toggle for adding the current course's program price and sku information to user
 #                                metadata
-# .. feature_toggle_category: experiments
-# .. feature_toggle_use_cases: monitored_rollout
-# .. feature_toggle_creation_date: 2019-3-12
-# .. feature_toggle_expiration_date: None
-# .. feature_toggle_warnings: None
-# .. feature_toggle_tickets: REVEM-118, REVEM-206
-# .. feature_toggle_status: supported
+# .. toggle_category: experiments
+# .. toggle_use_cases: monitored_rollout
+# .. toggle_creation_date: 2019-3-12
+# .. toggle_expiration_date: None
+# .. toggle_warnings: None
+# .. toggle_tickets: REVEM-118, REVEM-206
+# .. toggle_status: supported
 PROGRAM_PRICE_FLAG = WaffleFlag(
     waffle_namespace=experiments_namespace,
     flag_name=u'add_program_price',
     flag_undefined_default=False
 )
 
-# .. feature_toggle_name: experiments.add_dashboard_info
-# .. feature_toggle_type: flag
-# .. feature_toggle_default: False
-# .. feature_toggle_description: Toggle for adding info about each course to the dashboard metadata
-# .. feature_toggle_category: experiments
-# .. feature_toggle_use_cases: monitored_rollout
-# .. feature_toggle_creation_date: 2019-3-28
-# .. feature_toggle_expiration_date: None
-# .. feature_toggle_warnings: None
-# .. feature_toggle_tickets: REVEM-118
-# .. feature_toggle_status: supported
+# .. toggle_name: experiments.add_dashboard_info
+# .. toggle_type: feature_flag
+# .. toggle_default: False
+# .. toggle_description: Toggle for adding info about each course to the dashboard metadata
+# .. toggle_category: experiments
+# .. toggle_use_cases: monitored_rollout
+# .. toggle_creation_date: 2019-3-28
+# .. toggle_expiration_date: None
+# .. toggle_warnings: None
+# .. toggle_tickets: REVEM-118
+# .. toggle_status: supported
 DASHBOARD_INFO_FLAG = WaffleFlag(experiments_namespace,
                                  u'add_dashboard_info',
                                  flag_undefined_default=False)

diff --git a/lms/envs/common.py b/lms/envs/common.py
@@ -92,7 +92,19 @@
     # in sync with the corresponding ones in cms/envs/common.py
     'ENABLE_DISCUSSION_SERVICE': True,
     'ENABLE_TEXTBOOK': True,
-    'ENABLE_STUDENT_NOTES': True,  # enables the student notes API and UI.
+
+    # .. toggle_name: ENABLE_STUDENT_NOTES
+    # .. toggle_type: feature_flag
+    # .. toggle_default: True
+    # .. toggle_description: Enables the Student Notes API and UI.
+    # .. toggle_category: ????
+    # .. toggle_use_cases: open_edx
+    # .. toggle_creation_date: 2014-11-13
+    # .. toggle_expiration_date: None
+    # .. toggle_warnings: None
+    # .. toggle_tickets: TNL-659
+    # .. toggle_status: supported
+    'ENABLE_STUDENT_NOTES': True,
 
     # discussion home panel, which includes a subscription on/off setting for discussion digest emails.
     # this should remain off in production until digest notifications are online.
@@ -111,6 +123,17 @@
 
     'ENABLE_MASQUERADE': True,  # allow course staff to change to student view of courseware
 
+    # .. toggle_name: ENABLE_SYSADMIN_DASHBOARD
+    # .. toggle_type: feature_flag
+    # .. toggle_default: False
+    # .. toggle_description: enables dashboard at /syadmin/ for django staff, for seeing overview of system status, for deleting and loading courses, for seeing log of git imports of courseware.
+    # .. toggle_category: admin
+    # .. toggle_use_cases: open_edx
+    # .. toggle_creation_date: 2013-12-12
+    # .. toggle_expiration_date: None
+    # .. toggle_warnings: some views are not performant when there are more than 100 courses
+    # .. toggle_tickets: None
+    # .. toggle_status: unsupported
     'ENABLE_SYSADMIN_DASHBOARD': False,  # sysadmin dashboard, to see what courses are loaded, to delete & load courses
 
     'DISABLE_LOGIN_BUTTON': False,  # used in systems where login is automatic, eg MIT SSL