docs: add ADR on Course Authoring Feature Flag Implementation Details (#212)

Co-authored-by: Taylor Payne <[email protected]>

Author: rodmgwgu

CHANGELOG.rst

@@ -18,6 +18,7 @@ Added
 =====
 
 * ADR on the AuthZ for Course Authoring implementation plan.
+* ADR on the AuthZ for Course Authoring Feature Flag Implementation Details.
 
 0.20.0 - 2025-11-27
 ********************

docs/decisions/0010-course-authoring-flag.rst

@@ -0,0 +1,98 @@
+0010: AuthZ for Course Authoring - Feature Flag Implementation Details
+######################################################################
+
+Status
+******
+
+**Draft**
+
+Context
+*******
+
+We need to implement the new RBAC functionality for course authoring behind a Waffle flag as a
+beta feature for several key reasons:
+
+- Enable incremental development without breaking existing functionality
+- Allow large sites to test performance and functionality at small scale before full deployment
+- Mitigate risks associated with the Verawood release timeline
+
+The feature flag must support enablement at multiple granularity levels:
+
+- **Course level**: Individual courses
+- **Organization level**: All courses within an organization
+- **Instance level**: All courses across the entire instance
+
+Detailed implementation research can be found in the
+`Authoring Waffle Flag Implementation Spike`_.
+
+Decision
+********
+
+**Implementation Approach**
+
+- Implement as a Waffle flag with multi-level support:
+
+  - **Course level**: Using `WaffleFlagCourseOverrideModel`_
+  - **Organization level**: Using `WaffleFlagOrgOverrideModel`_
+  - **Instance level**: Using standard Waffle Switch
+
+- **Flag Configuration**
+
+  - Flag name: ``authz.enable_course_authoring``
+  - Management via Django Admin UI or management command
+  - Deprecation scheduled after 2 Open edX releases (after Willow)
+
+**Platform Integration**
+
+- All openedx-platform code related to course authoring must respect the flag state
+- Multi-course endpoints must handle both legacy and new AuthZ mechanisms simultaneously
+- Bidirectional migration process will be implemented (details in separate ADR)
+
+**Migration Behavior**
+
+When the flag state changes, automatic migration occurs immediately:
+
+- **Flag enabled**: Legacy role assignments migrate to new system and are removed from legacy
+  system
+- **Flag disabled**: New system role assignments migrate to legacy system and are removed from
+  new system
+
+  *Note: Roles without legacy equivalents remain in the new system and are not migrated*
+
+
+Consequences
+************
+
+- Documentation will be created for explaining the feature flag
+- Documentation will be created for comparing roles between the legacy and new AuthZ systems
+- A DEPR ticket will be created to track the deprecation of the feature flag after Willow
+
+Rejected Alternatives
+*********************
+
+**Instance-level only flag implementation**
+  Makes testing difficult on large instances with mixed requirements.
+
+**Django setting implementation**
+  Requires deployment and service restart for flag changes, increasing testing complexity and risk.
+
+**Per-user level implementation**
+  Creates inconsistent permission experiences within the same course. Course staff could
+  attempt to set permissions in one system for users operating in another system, resulting
+  in ineffective permission changes.
+
+References
+**********
+
+* `How to Implement the right toggle type`_
+* `Authoring Waffle Flag Implementation Spike`_
+
+.. _How to Implement the right toggle type: https://docs.openedx.org/projects/edx-toggles/en/
+   latest/how_to/implement_the_right_toggle_type.html#implementing-the-right-toggle-class
+.. _Authoring Waffle Flag Implementation Spike: https://openedx.atlassian.net/wiki/spaces/OEPM/
+   pages/5646221313/Spike+-+RBAC+AuthZ+-+Authoring+Waffle+Flag+Implementation
+.. _WaffleFlagCourseOverrideModel: https://github.com/openedx/openedx-platform/blob/
+   22485757573d32e3c0cb1c36855d83bcd2b1251d/openedx/core/djangoapps/waffle_utils/models.py#L14
+.. _WaffleFlagOrgOverrideModel: https://github.com/openedx/openedx-platform/blob/
+   22485757573d32e3c0cb1c36855d83bcd2b1251d/openedx/core/djangoapps/waffle_utils/models.py#L75
+