Skip to content

ARCHBOM-1721: docs: update toggle docs #27222

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
robrap merged 1 commit into from
Apr 5, 2021
Merged

ARCHBOM-1721: docs: update toggle docs #27222

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 12 additions & 2 deletions cms/djangoapps/contentstore/config/waffle.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,19 +12,29 @@
WAFFLE_NAMESPACE = 'studio'

# Switches
# TODO: Replace with WaffleSwitch(). See waffle() docstring.
ENABLE_ACCESSIBILITY_POLICY_PAGE = 'enable_policy_page'


def waffle():
"""
Returns the namespaced, cached, audited Waffle Switch class for Studio pages.
Deprecated: Returns the namespaced, cached, audited Waffle Switch class for Studio pages.

IMPORTANT: Do NOT copy this pattern and do NOT use this to reference new switches.
Instead, replace the string constant above with the actual switch instance.
For example::

ENABLE_ACCESSIBILITY_POLICY_PAGE = WaffleSwitch(f'{WAFFLE_NAMESPACE}.enable_policy_page')
"""
return LegacyWaffleSwitchNamespace(name=WAFFLE_NAMESPACE, log_prefix='Studio: ')


def waffle_flags():
"""
Returns the namespaced, cached, audited Waffle Flag class for Studio pages.
Deprecated: Returns the namespaced, cached, audited Waffle Flag class for Studio pages.

IMPORTANT: Do NOT copy this pattern and do NOT use this to reference new flags.
See waffle() docstring for more details.
"""
return LegacyWaffleFlagNamespace(name=WAFFLE_NAMESPACE, log_prefix='Studio: ')

Expand Down
9 changes: 2 additions & 7 deletions cms/djangoapps/contentstore/toggles.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,31 +22,26 @@
WAFFLE_NAMESPACE = 'contentstore'
WAFFLE_FLAG_NAMESPACE = LegacyWaffleFlagNamespace(name=WAFFLE_NAMESPACE, log_prefix='Contentstore: ')

# Waffle flag to split library to new view.
# .. toggle_name: split_library_on_studio_dashboard
# .. toggle_implementation: WaffleFlag
# .. toggle_default: False
# .. toggle_description: Studio dashboard
# .. toggle_description: Enables data new view for library on studio dashboard.
# .. toggle_use_cases: open_edx
# .. toggle_creation_date: 2020-07-8
# .. toggle_target_removal_date: None

@robrap robrap Apr 5, 2021

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewer Note: This PR should be removing toggle_target_removal_date: None in cases where toggle_use_cases does not include temporary. I think they are all the correct cases, but you don't need to spend a lot of time reviewing that to make sure it is perfect. It is an improvement that should help with the copy/paste contagion until we get some additional linting to give us what we want.

# .. toggle_warnings: ??
# .. toggle_tickets: TNL-7536
SPLIT_LIBRARY_ON_DASHBOARD = LegacyWaffleFlag(
waffle_namespace=LegacyWaffleFlagNamespace(name=WAFFLE_NAMESPACE),
flag_name='split_library_on_studio_dashboard',
module_name=__name__
)

# Waffle flag to enable olx validation during course import.
# .. toggle_name: course_import_olx_validation
# .. toggle_implementation: WaffleFlag
# .. toggle_default: False
# .. toggle_description: Studio Import
# .. toggle_description: Enables olx validation during course import.
# .. toggle_use_cases: open_edx
# .. toggle_creation_date: 2021-04-01
# .. toggle_target_removal_date: 2021-05-01
# .. toggle_warnings: ??
# .. toggle_tickets: TNL-8151
COURSE_IMPORT_OLX_VALIDATION = LegacyWaffleFlag(
waffle_namespace=LegacyWaffleFlagNamespace(name=WAFFLE_NAMESPACE),
Expand Down
4 changes: 0 additions & 4 deletions cms/envs/common.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -375,8 +375,6 @@
# default because enabling allows a method to bypass password policy.
# .. toggle_use_cases: open_edx
# .. toggle_creation_date: 2020-02-21
# .. toggle_target_removal_date: None
# .. toggle_warnings: None
# .. toggle_tickets: 'https://github.com/edx/edx-platform/pull/21616'
'ENABLE_CHANGE_USER_PASSWORD_ADMIN': False,

Expand Down Expand Up @@ -443,8 +441,6 @@
# otherwise the course creation functionality will work as it should.
# .. toggle_use_cases: open_edx
# .. toggle_creation_date: 2013-12-02
# .. toggle_target_removal_date: None
# .. toggle_tickets: None
# .. toggle_warnings: Another toggle DISABLE_LIBRARY_CREATION overrides DISABLE_COURSE_CREATION, if present.
'DISABLE_COURSE_CREATION': False,

Expand Down
3 changes: 0 additions & 3 deletions common/djangoapps/util/milestones_helpers.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,9 +30,6 @@
# the Open edX platform. (see https://github.com/edx/edx-milestones)
# .. toggle_use_cases: open_edx
# .. toggle_creation_date: 2014-11-21
# .. toggle_target_removal_date: None
# .. toggle_warnings: None
# .. toggle_tickets: None
ENABLE_MILESTONES_APP = SettingDictToggle("FEATURES", "MILESTONES_APP", default=False, module_name=__name__)


Expand Down
3 changes: 0 additions & 3 deletions lms/djangoapps/bulk_email/models.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -484,9 +484,6 @@ class BulkEmailFlag(ConfigurationModel):
is not available.
.. toggle_use_cases: open_edx
.. toggle_creation_date: 2016-05-05
.. toggle_target_removal_date: None
.. toggle_warnings: None
.. toggle_tickets: None
"""
# boolean field 'enabled' inherited from parent ConfigurationModel
require_course_email_auth = models.BooleanField(default=True)
Expand Down
4 changes: 0 additions & 4 deletions lms/djangoapps/course_api/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,6 @@
# users, this limit is 10 requests/minute.
# .. toggle_use_cases: circuit_breaker
# .. toggle_creation_date: 2018-06-12
# .. toggle_target_removal_date: None
# .. toggle_warnings: None
# .. toggle_tickets: https://openedx.atlassian.net/browse/LEARNER-5527
USE_RATE_LIMIT_2_FOR_COURSE_LIST_API = LegacyWaffleSwitch(WAFFLE_SWITCH_NAMESPACE, 'rate_limit_2', __name__)
# .. toggle_name: course_list_api_rate_limit.rate_limit_10
Expand All @@ -23,7 +21,5 @@
# users, this limit is 20 requests/minute.
# .. toggle_use_cases: circuit_breaker
# .. toggle_creation_date: 2018-06-12
# .. toggle_target_removal_date: None
# .. toggle_warnings: None
# .. toggle_tickets: https://openedx.atlassian.net/browse/LEARNER-5527
USE_RATE_LIMIT_10_FOR_COURSE_LIST_API = LegacyWaffleSwitch(WAFFLE_SWITCH_NAMESPACE, 'rate_limit_10', __name__)
1 change: 0 additions & 1 deletion lms/djangoapps/course_api/blocks/toggles.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,6 @@
# .. toggle_creation_date: 2019-09-27
# .. toggle_target_removal_date: None
# .. toggle_warnings: This temporary feature toggle does not have a target removal date.
# .. toggle_tickets: None
HIDE_ACCESS_DENIALS_FLAG = LegacyWaffleFlag(
waffle_namespace=COURSE_BLOCKS_API_NAMESPACE,
flag_name='hide_access_denials',
Expand Down
3 changes: 0 additions & 3 deletions lms/djangoapps/courseware/toggles.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,6 @@
# .. toggle_implementation: CourseWaffleFlag
# .. toggle_default: False
# .. toggle_description: Supports staged rollout of the new micro-frontend-based implementation of the course exit page.
# .. toggle_category: micro-frontend
# .. toggle_use_cases: open_edx, temporary
# .. toggle_creation_date: 2020-10-02
# .. toggle_target_removal_date: None
Expand Down Expand Up @@ -95,7 +94,6 @@
# .. toggle_use_cases: temporary
# .. toggle_creation_date: 2020-10-07
# .. toggle_target_removal_date: None
# .. toggle_warnings: None
# .. toggle_tickets: MST-432
COURSEWARE_PROCTORING_IMPROVEMENTS = CourseWaffleFlag(
WAFFLE_FLAG_NAMESPACE, 'proctoring_improvements', __name__
Expand All @@ -111,7 +109,6 @@
# .. toggle_use_cases: temporary
# .. toggle_creation_date: 2021-02-09
# .. toggle_target_removal_date: 2021-05-01
# .. toggle_warnings: None
COURSEWARE_OPTIMIZED_RENDER_XBLOCK = CourseWaffleFlag(
WAFFLE_FLAG_NAMESPACE, 'optimized_render_xblock', __name__
)
Expand Down
3 changes: 0 additions & 3 deletions lms/djangoapps/discussion/config/settings.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,6 @@
# for daily digest. This setting enables deprecation of daily digest.
# .. toggle_use_cases: open_edx
# .. toggle_creation_date: 2020-03-09
# .. toggle_target_removal_date: None
# .. toggle_warnings: None
# .. toggle_tickets: None
ENABLE_FORUM_DAILY_DIGEST = 'enable_forum_daily_digest'


Expand Down
2 changes: 0 additions & 2 deletions lms/djangoapps/discussion/settings/common.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,6 @@ def plugin_settings(settings):
# .. toggle_description: If True, it adds an option to show/hide the discussions tab.
# .. toggle_use_cases: open_edx
# .. toggle_creation_date: 2015-06-15
# .. toggle_target_removal_date: None
# .. toggle_warnings: None
# .. toggle_tickets: https://github.com/edx/edx-platform/pull/8474
settings.FEATURES['ALLOW_HIDING_DISCUSSION_TAB'] = False
settings.DISCUSSION_SETTINGS = {
Expand Down
1 change: 0 additions & 1 deletion lms/djangoapps/grades/config/models.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,6 @@ class PersistentGradesEnabledFlag(ConfigurationModel):
.. toggle_use_cases: temporary
.. toggle_creation_date: 2016-08-26
.. toggle_target_removal_date: None
.. toggle_warnings: None
.. toggle_tickets: https://github.com/edx/edx-platform/pull/13329
"""
# this field overrides course-specific settings to enable the feature for all courses
Expand Down
37 changes: 20 additions & 17 deletions lms/djangoapps/grades/config/waffle.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,19 +21,18 @@
# for all courses.
# .. toggle_use_cases: open_edx
# .. toggle_creation_date: 2017-04-11
# .. toggle_target_removal_date: None
# .. toggle_tickets: https://github.com/edx/edx-platform/pull/14771
# .. toggle_warnings: This requires the PersistentGradesEnabledFlag to be enabled.
# TODO: Replace with WaffleSwitch(). See waffle_switch(name) docstring.
ASSUME_ZERO_GRADE_IF_ABSENT = 'assume_zero_grade_if_absent'
# .. toggle_name: grades.disable_regrade_on_policy_change
# .. toggle_implementation: WaffleSwitch
# .. toggle_default: False
# .. toggle_description: When enabled, a change in grading policy will not trigger re-grading.
# .. toggle_use_cases: open_edx
# .. toggle_creation_date: 2017-08-03
# .. toggle_target_removal_date: None
# .. toggle_warnings: None
# .. toggle_tickets: https://github.com/edx/edx-platform/pull/15733
# TODO: Replace with WaffleSwitch(). See waffle_switch(name) docstring.
DISABLE_REGRADE_ON_POLICY_CHANGE = 'disable_regrade_on_policy_change'

# Course Flags
Expand All @@ -45,9 +44,8 @@
# in edx-platform, but only in edx-proctoring.
# .. toggle_use_cases: open_edx
# .. toggle_creation_date: 2019-05-29
# .. toggle_target_removal_date: None
# .. toggle_warnings: None
# .. toggle_tickets: https://github.com/edx/edx-platform/pull/20719
# TODO: Replace with CourseWaffleFlag() from below. See waffle_flag(name) docstring.
REJECTED_EXAM_OVERRIDES_GRADE = 'rejected_exam_overrides_grade'
# .. toggle_name: grades.rejected_exam_overrides_grade
# .. toggle_implementation: CourseWaffleFlag
Expand All @@ -56,9 +54,8 @@
# is only valid for courses which actually have an end date.
# .. toggle_use_cases: open_edx
# .. toggle_creation_date: 2018-10-01
# .. toggle_target_removal_date: None
# .. toggle_warnings: None
# .. toggle_tickets: https://github.com/edx/edx-platform/pull/19026
# TODO: Replace with CourseWaffleFlag() from below. See waffle_flag(name) docstring.
ENFORCE_FREEZE_GRADE_AFTER_COURSE_END = 'enforce_freeze_grade_after_course_end'

# .. toggle_name: grades.writable_gradebook
Expand All @@ -68,9 +65,9 @@
# the writable gradebook is added to the instructor dashboard.
# .. toggle_use_cases: open_edx
# .. toggle_creation_date: 2018-10-03
# .. toggle_target_removal_date: None
# .. toggle_tickets: https://github.com/edx/edx-platform/pull/19054
# .. toggle_warnings: Enabling this requires that the `WRITABLE_GRADEBOOK_URL` setting be properly defined.
# TODO: Replace with CourseWaffleFlag() from below. See waffle_flag(name) docstring.
WRITABLE_GRADEBOOK = 'writable_gradebook'

# .. toggle_name: grades.bulk_management
Expand All @@ -80,35 +77,41 @@
# as we understand, this feature is now unused and obsolete.
# .. toggle_use_cases: open_edx
# .. toggle_creation_date: 2019-08-20
# .. toggle_target_removal_date: None
# .. toggle_warnings: None
# .. toggle_tickets: https://github.com/edx/edx-platform/pull/21389
# TODO: Replace with CourseWaffleFlag() from below. See waffle_flag(name) docstring.
BULK_MANAGEMENT = 'bulk_management'


def waffle():
"""
Returns the namespaced, cached, audited Waffle class for Grades.
Deprecated: Returns the namespaced, cached, audited Waffle class for Grades.

Note: Replace uses of this function with direct references to each switch.
See waffle_switch(name) docstring for details.
"""
return LegacyWaffleSwitchNamespace(name=WAFFLE_NAMESPACE, log_prefix='Grades: ')


def waffle_switch(name):
"""
Return the corresponding namespaced waffle switch.
Deprecated: Return the corresponding namespaced waffle switch.

IMPORTANT: Do NOT copy this pattern and do NOT use this to reference new switches.
Instead, replace the string constants above with the actual switch instances.
For example::

WARNING: do not replicate this pattern. Instead of declaring waffle switch names as strings, you should create
LegacyWaffleSwitch objects as top-level constants.
ASSUME_ZERO_GRADE_IF_ABSENT = WaffleSwitch(f'{WAFFLE_NAMESPACE}.assume_zero_grade_if_absent')
"""
return LegacyWaffleSwitch(waffle(), name, module_name=__name__)


def waffle_flags():
"""
Returns the namespaced, cached, audited Waffle flags dictionary for Grades.
Deprecated: Returns the namespaced, cached, audited Waffle flags dictionary for Grades.

WARNING: do not replicate this pattern. Instead of declaring waffle flag names as strings, you should create
LegacyWaffleFlag and CourseWaffleFlag objects as top-level constants.
IMPORTANT: Do NOT copy this pattern and do NOT use this to reference new flags.
Instead, replace the string constants above with the flag declarations below, and use
them directly.
"""
namespace = LegacyWaffleFlagNamespace(name=WAFFLE_NAMESPACE, log_prefix='Grades: ')
return {
Expand Down
9 changes: 2 additions & 7 deletions lms/djangoapps/instructor/toggles.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,27 +15,22 @@
# .. toggle_description: instructor
# .. toggle_use_cases: open_edx
# .. toggle_creation_date: 2020-07-8
# .. toggle_target_removal_date: None
# .. toggle_warnings: ??
# .. toggle_tickets: PROD-1309
DATA_DOWNLOAD_V2 = LegacyWaffleFlag(
waffle_namespace=WAFFLE_FLAG_NAMESPACE,
flag_name='enable_data_download_v2',
module_name=__name__,
)

# Waffle flag to use optimised is_small_course.
# .. toggle_name: verify_student.optimised_is_small_course
# .. toggle_implementation: WaffleFlag
# .. toggle_default: False
# .. toggle_description: Supports staged rollout to improved is_small_course method.
# .. toggle_category: instructor
# .. toggle_use_cases: open_edx
# .. toggle_creation_date: 2020-07-02
# .. toggle_target_removal_date: None
# .. toggle_warnings: n/a
# .. toggle_warnings: Description mentions staged rollout, but the use case is not set as temporary.
# This may actually be a temporary toggle.
# .. toggle_tickets: PROD-1740
# .. toggle_status: supported
OPTIMISED_IS_SMALL_COURSE = LegacyWaffleFlag(
waffle_namespace=WAFFLE_FLAG_NAMESPACE,
flag_name='optimised_is_small_course',
Expand Down
8 changes: 8 additions & 0 deletions lms/djangoapps/instructor_task/config/waffle.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,20 +8,28 @@
from openedx.core.djangoapps.waffle_utils import CourseWaffleFlag

WAFFLE_NAMESPACE = 'instructor_task'
# TODO: Remove and replace with direct references to each flag.
INSTRUCTOR_TASK_WAFFLE_FLAG_NAMESPACE = LegacyWaffleFlagNamespace(name=WAFFLE_NAMESPACE)
# TODO: Remove and replace with direct references to each switch.
WAFFLE_SWITCHES = LegacyWaffleSwitchNamespace(name=WAFFLE_NAMESPACE)

# Waffle switches
# TODO: Replace with WaffleSwitch(). See WAFFLE_SWITCHES comment.
OPTIMIZE_GET_LEARNERS_FOR_COURSE = 'optimize_get_learners_for_course'

# Course override flags
# TODO: Replace with WaffleFlag(). See waffle_flags() docstring.
GENERATE_PROBLEM_GRADE_REPORT_VERIFIED_ONLY = 'generate_problem_grade_report_verified_only'
# TODO: Replace with WaffleFlag(). See waffle_flags() docstring.
GENERATE_COURSE_GRADE_REPORT_VERIFIED_ONLY = 'generate_course_grade_report_verified_only'


def waffle_flags():
"""
Returns the namespaced, cached, audited Waffle flags dictionary for Grades.

IMPORTANT: Do NOT copy this dict pattern and do NOT add new flags to this dict.
Instead, replace the string constants above with the actual flag instances.
"""
return {
GENERATE_PROBLEM_GRADE_REPORT_VERIFIED_ONLY: CourseWaffleFlag(
Expand Down
Loading