Merge pull request #24815 from regisb/regisb/document-feature-toggles

[BD-21] Document feature toggles
2020-09-17 13:46:46 -04:00
parent 282f33a603 a4ba4ae45e
commit 90bc2ffdab
30 changed files with 541 additions and 294 deletions
--- a/openedx/core/djangoapps/user_api/accounts/toggles.py
+++ b/openedx/core/djangoapps/user_api/accounts/toggles.py
@@ -11,13 +11,12 @@ from openedx.core.djangoapps.waffle_utils import WaffleFlag
 # .. toggle_implementation: WaffleFlag
 # .. toggle_default: False
 # .. toggle_description: Supports staged rollout of a new micro-frontend-based implementation of the order history page.
-# .. toggle_category: micro-frontend
-# .. toggle_use_cases: incremental_release, open_edx
+# .. toggle_use_cases: temporary, open_edx
 # .. toggle_creation_date: 2019-04-11
-# .. toggle_expiration_date: 2020-12-31
-# .. toggle_warnings: Also set settings.ORDER_HISTORY_MICROFRONTEND_URL and site's ENABLE_ORDER_HISTORY_MICROFRONTEND.
+# .. toggle_target_removal_date: 2020-12-31
+# .. toggle_warnings: Also set settings.ORDER_HISTORY_MICROFRONTEND_URL and site's
+#   ENABLE_ORDER_HISTORY_MICROFRONTEND.
 # .. toggle_tickets: DEPR-17
-# .. toggle_status: supported
 REDIRECT_TO_ORDER_HISTORY_MICROFRONTEND = WaffleFlag('order_history', 'redirect_to_microfrontend', __name__)


@@ -32,13 +31,11 @@ def should_redirect_to_order_history_microfrontend():
 # .. toggle_implementation: WaffleFlag
 # .. toggle_default: False
 # .. toggle_description: Supports staged rollout of a new micro-frontend-based implementation of the account page.
-# .. toggle_category: micro-frontend
-# .. toggle_use_cases: incremental_release, open_edx
+# .. toggle_use_cases: temporary, open_edx
 # .. toggle_creation_date: 2019-04-30
-# .. toggle_expiration_date: 2020-12-31
+# .. toggle_target_removal_date: 2020-12-31
 # .. toggle_warnings: Also set settings.ACCOUNT_MICROFRONTEND_URL and site's ENABLE_ACCOUNT_MICROFRONTEND.
 # .. toggle_tickets: DEPR-17
-# .. toggle_status: supported
 REDIRECT_TO_ACCOUNT_MICROFRONTEND = WaffleFlag('account', 'redirect_to_microfrontend', __name__)


--- a/openedx/core/djangoapps/user_authn/config/waffle.py
+++ b/openedx/core/djangoapps/user_authn/config/waffle.py
@@ -11,14 +11,13 @@ _WAFFLE_SWITCH_NAMESPACE = WaffleSwitchNamespace(name=_WAFFLE_NAMESPACE, log_pre
 # .. toggle_name: user_authn.enable_login_using_thirdparty_auth_only
 # .. toggle_implementation: WaffleSwitch
 # .. toggle_default: False
-# .. toggle_description: When enabled, users must be sign in using their allowed domain SSO account.
-# .. toggle_category: authn
-# .. toggle_use_cases: incremental_release
+# .. toggle_description: When enabled, users must be sign in using their allowed domain SSO account. This includes sign-
+#   ins to the Django admin dashboard at "/admin".
+# .. toggle_use_cases: temporary
 # .. toggle_creation_date: 2019-11-20
-# .. toggle_expiration_date: 2020-01-31
+# .. toggle_target_removal_date: 2020-01-31
 # .. toggle_warnings: Requires THIRD_PARTY_AUTH_ONLY_DOMAIN to also be set.
 # .. toggle_tickets: ENT-2461
-# .. toggle_status: supported
 ENABLE_LOGIN_USING_THIRDPARTY_AUTH_ONLY = WaffleSwitch(
    _WAFFLE_SWITCH_NAMESPACE,
    'enable_login_using_thirdparty_auth_only',
--- a/openedx/core/djangoapps/user_authn/views/register.py
+++ b/openedx/core/djangoapps/user_authn/views/register.py
@@ -96,17 +96,14 @@ REGISTRATION_UTM_CREATED_AT = 'registration_utm_created_at'
 REGISTER_USER = Signal(providing_args=["user", "registration"])


-# .. feature_toggle_name: registration.enable_failure_logging
-# .. feature_toggle_type: flag
-# .. feature_toggle_default: False
-# .. feature_toggle_description: Enable verbose logging of registration failure messages
-# .. feature_toggle_category: registration
-# .. feature_toggle_use_cases: monitored_rollout
-# .. feature_toggle_creation_date: 2020-04-30
-# .. feature_toggle_expiration_date: 2020-06-01
-# .. feature_toggle_warnings: None
-# .. feature_toggle_tickets: None
-# .. feature_toggle_status: supported
+# .. toggle_name: registration.enable_failure_logging
+# .. toggle_type: flag
+# .. toggle_default: False
+# .. toggle_description: Enable verbose logging of registration failure messages
+# .. toggle_use_cases: temporary
+# .. toggle_creation_date: 2020-04-30
+# .. toggle_target_removal_date: 2020-06-01
+# .. toggle_warnings: This temporary feature toggle does not have a target removal date.
 REGISTRATION_FAILURE_LOGGING_FLAG = WaffleFlag(
    waffle_namespace=WaffleFlagNamespace(name=u'registration'),
    flag_name=u'enable_failure_logging',
--- a/openedx/core/djangoapps/video_config/models.py
+++ b/openedx/core/djangoapps/video_config/models.py
@@ -23,6 +23,14 @@ class HLSPlaybackEnabledFlag(ConfigurationModel):
    take effect.

    .. no_pii:
+
+    .. toggle_name: HLSPlaybackEnabledFlag.enabled_for_all_courses
+    .. toggle_implementation: ConfigurationModel
+    .. toggle_default: False
+    .. toggle_description: Add the "hls" profile to all displayed videos on the platform.
+    .. toggle_use_cases:  open_edx
+    .. toggle_creation_date: 2017-04-19
+    .. toggle_tickets: https://github.com/edx/edx-platform/pull/14924
    """
    # this field overrides course-specific settings
    enabled_for_all_courses = BooleanField(default=False)
@@ -65,6 +73,14 @@ class CourseHLSPlaybackEnabledFlag(ConfigurationModel):
    enabled for this to take effect.

    .. no_pii:
+
+    .. toggle_name: CourseHLSPlaybackEnabledFlag.course_id
+    .. toggle_implementation: ConfigurationModel
+    .. toggle_default: False
+    .. toggle_description: Add the "hls" profile to all displayed videos for a single course.
+    .. toggle_use_cases:  open_edx
+    .. toggle_creation_date: 2017-04-19
+    .. toggle_tickets: https://github.com/edx/edx-platform/pull/14924
    """
    KEY_FIELDS = ('course_id',)

--- a/openedx/core/djangoapps/video_pipeline/api.py
+++ b/openedx/core/djangoapps/video_pipeline/api.py
@@ -9,7 +9,6 @@ from django.core.exceptions import ObjectDoesNotExist
 from oauth2_provider.models import Application
 from slumber.exceptions import HttpClientError

-from openedx.core.djangoapps.video_pipeline.config.waffle import ENABLE_VEM_PIPELINE, waffle_flags
 from openedx.core.djangoapps.video_pipeline.models import VEMPipelineIntegration, VideoPipelineIntegration
 from openedx.core.djangoapps.video_pipeline.utils import create_video_pipeline_api_client

--- a/openedx/core/djangoapps/video_pipeline/config/waffle.py
+++ b/openedx/core/djangoapps/video_pipeline/config/waffle.py
@@ -8,8 +8,26 @@ from openedx.core.djangoapps.waffle_utils import CourseWaffleFlag, WaffleFlag, W
 # Videos Namespace
 WAFFLE_NAMESPACE = 'videos'

-# Waffle flag telling whether youtube is deprecated.
+# .. toggle_name: videos.deprecate_youtube
+# .. toggle_implementation: WaffleFlag
+# .. toggle_default: False
+# .. toggle_description: Waffle flag telling whether youtube is deprecated. When enabled, videos are no longer uploaded
+#   to YouTube as part of the video pipeline.
+# .. toggle_use_cases: open_edx
+# .. toggle_creation_date: 2018-08-03
+# .. toggle_tickets: https://github.com/edx/edx-platform/pull/18765
 DEPRECATE_YOUTUBE = 'deprecate_youtube'
+# .. toggle_name: videos.enable_devstack_video_uploads
+# .. toggle_implementation: WaffleFlag
+# .. toggle_default: False
+# .. toggle_description: When enabled, use Multi-Factor Authentication (MFA) for authenticating to AWS. These short-
+#   lived access tokens are well suited for development (probably?). [At the time of annotation, the exact consequences
+#   of enabling this feature toggle are uncertain.]
+# .. toggle_use_cases: open_edx
+# .. toggle_creation_date: 2020-03-12
+# .. toggle_warnings: Enabling this feature requires that the ROLE_ARN, MFA_SERIAL_NUMBER, MFA_TOKEN settings are
+#   properly defined.
+# .. toggle_tickets: https://github.com/edx/edx-platform/pull/23375
 ENABLE_DEVSTACK_VIDEO_UPLOADS = 'enable_devstack_video_uploads'
 ENABLE_VEM_PIPELINE = 'enable_vem_pipeline'

--- a/openedx/core/djangoapps/video_pipeline/models.py
+++ b/openedx/core/djangoapps/video_pipeline/models.py
@@ -50,6 +50,15 @@ class VEMPipelineIntegration(ConfigurationModel):
    Manages configuration for connecting to the video encode manager service and using its API.

    .. no_pii:
+
+    .. toggle_name: VEMPipelineIntegration.enabled
+    .. toggle_implementation: ConfigurationModel
+    .. toggle_default: False
+    .. toggle_description: Send videos to the Video Encode Manager (VEM) as part of the
+      video pipeline.
+    .. toggle_use_cases:  open_edx
+    .. toggle_creation_date: 2020-06-04
+    .. toggle_tickets: https://github.com/edx/edx-platform/pull/24093
    """
    client_name = models.CharField(
        max_length=100,
@@ -80,9 +89,18 @@ class VEMPipelineIntegration(ConfigurationModel):
@python_2_unicode_compatible
 class VideoUploadsEnabledByDefault(ConfigurationModel):
    """
-    Enables video uploads enabled By default feature across the platform.
+    Enables video uploads across the platform.

    .. no_pii:
+
+    .. toggle_name: VideoUploadsEnabledByDefault.enabled_for_all_courses
+    .. toggle_implementation: ConfigurationModel
+    .. toggle_default: False
+    .. toggle_description: Allow video uploads for all courses of the platform. This
+      enables the "Video Uploads" menu in the CMS.
+    .. toggle_use_cases:  open_edx
+    .. toggle_creation_date: 2017-11-10
+    .. toggle_tickets: https://github.com/edx/edx-platform/pull/16536
    """
    # this field overrides course-specific settings
    enabled_for_all_courses = models.BooleanField(default=False)
@@ -122,10 +140,18 @@ class VideoUploadsEnabledByDefault(ConfigurationModel):
@python_2_unicode_compatible
 class CourseVideoUploadsEnabledByDefault(ConfigurationModel):
    """
-    Enables video uploads enabled by default feature for a specific course. Its global feature must be
-    enabled for this to take effect.
+    Enables video uploads for a specific course.

    .. no_pii:
+
+    .. toggle_name: CourseVideoUploadsEnabledByDefault.course_id
+    .. toggle_implementation: ConfigurationModel
+    .. toggle_default: False
+    .. toggle_description: Allow video uploads for a specific course. This enables the
+      "Video Uploads" menu in the CMS.
+    .. toggle_use_cases:  open_edx
+    .. toggle_creation_date: 2017-11-10
+    .. toggle_tickets: https://github.com/edx/edx-platform/pull/16536
    """
    KEY_FIELDS = ('course_id',)

--- a/openedx/core/djangoapps/video_pipeline/tests/test_api.py
+++ b/openedx/core/djangoapps/video_pipeline/tests/test_api.py
@@ -7,14 +7,11 @@ import json
 import ddt
 from django.test.testcases import TestCase
 from mock import Mock, patch
-from opaque_keys.edx.locations import CourseLocator
 from slumber.exceptions import HttpClientError
 from student.tests.factories import UserFactory

 from openedx.core.djangoapps.video_pipeline.api import update_3rd_party_transcription_service_credentials
-from openedx.core.djangoapps.video_pipeline.config.waffle import ENABLE_VEM_PIPELINE, waffle_flags
 from openedx.core.djangoapps.video_pipeline.tests.mixins import VideoPipelineMixin
-from openedx.core.djangoapps.waffle_utils.testutils import override_waffle_flag


@ddt.ddt
--- a/openedx/core/djangoapps/waffle_utils/init.py
+++ b/openedx/core/djangoapps/waffle_utils/init.py
@@ -378,17 +378,14 @@ def _get_waffle_flag_custom_metrics_set():
    waffle_flag_custom_metrics = waffle_flag_custom_metrics if waffle_flag_custom_metrics else []
    return set(waffle_flag_custom_metrics)

-    # .. toggle_name: WAFFLE_FLAG_CUSTOM_METRICS
-    # .. toggle_implementation: DjangoSetting
-    # .. toggle_default: False
-    # .. toggle_description: A list of waffle flag to track with custom metrics having values of (True, False, or Both).
-    # .. toggle_category: monitoring
-    # .. toggle_use_cases: opt_in
-    # .. toggle_creation_date: 2020-06-17
-    # .. toggle_expiration_date: None
-    # .. toggle_tickets: None
-    # .. toggle_status: supported
-    # .. toggle_warnings: Intent is for temporary research (1 day - several weeks) of a flag's usage.
+# .. toggle_name: WAFFLE_FLAG_CUSTOM_METRICS
+# .. toggle_implementation: DjangoSetting
+# .. toggle_default: False
+# .. toggle_description: A list of waffle flag to track with custom metrics having
+#   values of (True, False, or Both).
+# .. toggle_use_cases: opt_in
+# .. toggle_creation_date: 2020-06-17
+# .. toggle_warnings: Intent is for temporary research (1 day - several weeks) of a flag's usage.
 _WAFFLE_FLAG_CUSTOM_METRICS = 'WAFFLE_FLAG_CUSTOM_METRICS'

 # set of waffle flags that should be instrumented with custom metrics
--- a/openedx/features/course_duration_limits/models.py
+++ b/openedx/features/course_duration_limits/models.py
@@ -18,6 +18,15 @@ class CourseDurationLimitConfig(StackedConfigurationModel):
    Configuration to manage the Course Duration Limit facility.

    .. no_pii:
+
+    .. toggle_name: CourseDurationLimitConfig.enabled
+    .. toggle_implementation: ConfigurationModel
+    .. toggle_default: False
+    .. toggle_description: When enabled, users will have a limited time to complete and audit the course. The exact
+       duration is given by the "weeks_to_complete" course detail. When enabled, it is necessary to also define the
+       "enabled_as_of" flag: only enrollments created after this date will be affected.
+    .. toggle_use_cases: opt_in
+    .. toggle_creation_date: 2018-11-02
    """

    STACKABLE_FIELDS = ('enabled', 'enabled_as_of')
--- a/openedx/features/course_experience/init.py
+++ b/openedx/features/course_experience/init.py
@@ -90,13 +90,12 @@ COURSE_PRE_START_ACCESS_FLAG = WaffleFlag(WAFFLE_FLAG_NAMESPACE, 'pre_start_acce
 # .. toggle_implementation: CourseWaffleFlag
 # .. toggle_default: False
 # .. toggle_description: Used with our integration with CourseTalk to display reviews for a course.
-# .. toggle_category: course_experience
-# .. toggle_use_cases: monitored_rollout
+# .. toggle_use_cases: temporary
 # .. toggle_creation_date: 2017-06-19
-# .. toggle_expiration_date: ???
-# .. toggle_warnings: We are no longer integrating with CourseTalk, so this probably should be deprecated and the code for reviews should be removed.
+# .. toggle_target_removal_date: None
+# .. toggle_warnings: We are no longer integrating with CourseTalk, so this probably should be deprecated and the code
+#   for reviews should be removed. This temporary feature toggle should have a target removal date.
 # .. toggle_tickets: DEPR-48
-# .. toggle_status: unsupported
 SHOW_REVIEWS_TOOL_FLAG = CourseWaffleFlag(WAFFLE_FLAG_NAMESPACE, 'show_reviews_tool', __name__)

 # Waffle flag to enable the setting of course goals.
@@ -104,13 +103,10 @@ SHOW_REVIEWS_TOOL_FLAG = CourseWaffleFlag(WAFFLE_FLAG_NAMESPACE, 'show_reviews_t
 # .. toggle_implementation: CourseWaffleFlag
 # .. toggle_default: False
 # .. toggle_description: Used to determine whether or not to use course goals for the particular course.
-# .. toggle_category: course_experience
-# .. toggle_use_cases: opt_out, monitored_rollout
+# .. toggle_use_cases: opt_out, temporary
 # .. toggle_creation_date: 2017-09-11
-# .. toggle_expiration_date: ???
-# .. toggle_warnings: N/A
-# .. toggle_tickets: N/A
-# .. toggle_status: supported
+# .. toggle_target_removal_date: None
+# .. toggle_warnings: This temporary feature toggle does not have a target removal date.
 ENABLE_COURSE_GOALS = CourseWaffleFlag(WAFFLE_FLAG_NAMESPACE, 'enable_course_goals', __name__)

 # Waffle flag to control the display of the hero
@@ -124,13 +120,10 @@ UPGRADE_DEADLINE_MESSAGE = CourseWaffleFlag(WAFFLE_FLAG_NAMESPACE, 'upgrade_dead
 # .. toggle_implementation: CourseWaffleFlag
 # .. toggle_default: False
 # .. toggle_description: Used to switch between 'welcome message' and 'latest update' on the course home page.
-# .. toggle_category: course_experience
 # .. toggle_use_cases: opt_out
 # .. toggle_creation_date: 2017-09-11
-# .. toggle_expiration_date: ???
-# .. toggle_warnings: This is meant to be configured using waffle_utils course override only.  Either do not create the actual waffle flag, or be sure to unset the flag even for Superusers.
-# .. toggle_tickets: N/A
-# .. toggle_status: supported
+# .. toggle_warnings: This is meant to be configured using waffle_utils course override only. Either do not create the
+#   actual waffle flag, or be sure to unset the flag even for Superusers.
 LATEST_UPDATE_FLAG = CourseWaffleFlag(WAFFLE_FLAG_NAMESPACE, 'latest_update', __name__)

 # Waffle flag to enable anonymous access to a course
--- a/openedx/features/course_experience/waffle.py
+++ b/openedx/features/course_experience/waffle.py
@@ -13,13 +13,8 @@ WAFFLE_NAMESPACE = u'course_experience'
 # .. toggle_implementation: CourseWaffleFlag
 # .. toggle_default: False
 # .. toggle_description: Used to determine whether to show custom HTML in the sidebar on the internal course about page.
-# .. toggle_category: course-experience
 # .. toggle_use_cases: open_edx
 # .. toggle_creation_date: 2018-01-26
-# .. toggle_expiration_date: ???
-# .. toggle_warnings: N/A
-# .. toggle_tickets: N/A
-# .. toggle_status: supported
 ENABLE_COURSE_ABOUT_SIDEBAR_HTML = u'enable_about_sidebar_html'


--- a/openedx/features/discounts/applicability.py
+++ b/openedx/features/discounts/applicability.py
@@ -26,17 +26,15 @@ from openedx.features.discounts.models import DiscountPercentageConfig, Discount
 from student.models import CourseEnrollment
 from track import segment

-# .. feature_toggle_name: discounts.enable_discounting
-# .. feature_toggle_type: flag
-# .. feature_toggle_default: False
-# .. feature_toggle_description: Toggle discounts always being disabled
-# .. feature_toggle_category: discounts
-# .. feature_toggle_use_cases: monitored_rollout
-# .. feature_toggle_creation_date: 2019-4-16
-# .. feature_toggle_expiration_date: None
-# .. feature_toggle_warnings: None
-# .. feature_toggle_tickets: REVEM-282
-# .. feature_toggle_status: supported
+# .. toggle_name: discounts.enable_discounting
+# .. toggle_type: flag
+# .. toggle_default: False
+# .. toggle_description: Toggle discounts always being disabled
+# .. toggle_use_cases: temporary
+# .. toggle_creation_date: 2019-4-16
+# .. toggle_target_removal_date: None
+# .. toggle_tickets: REVEM-282
+# .. toggle_warnings: This temporary feature toggle does not have a target removal date.
 DISCOUNT_APPLICABILITY_FLAG = WaffleFlag(
    waffle_namespace=WaffleFlagNamespace(name=u'discounts'),
    flag_name=u'enable_discounting',
--- a/openedx/features/learner_profile/toggles.py
+++ b/openedx/features/learner_profile/toggles.py
@@ -15,13 +15,11 @@ WAFFLE_FLAG_NAMESPACE = WaffleFlagNamespace(name='learner_profile')
 # .. toggle_implementation: WaffleFlag
 # .. toggle_default: False
 # .. toggle_description: Supports staged rollout of a new micro-frontend-based implementation of the profile page.
-# .. toggle_category: micro-frontend
-# .. toggle_use_cases: incremental_release, open_edx
+# .. toggle_use_cases: temporary, open_edx
 # .. toggle_creation_date: 2019-02-19
-# .. toggle_expiration_date: 2020-12-31
+# .. toggle_target_removal_date: 2020-12-31
 # .. toggle_warnings: Also set settings.PROFILE_MICROFRONTEND_URL and site's ENABLE_PROFILE_MICROFRONTEND.
 # .. toggle_tickets: DEPR-17
-# .. toggle_status: supported
 REDIRECT_TO_PROFILE_MICROFRONTEND = WaffleFlag(WAFFLE_FLAG_NAMESPACE, 'redirect_to_microfrontend', __name__)