From 578e61511ccbc6266cbfb84dc6b0e8867ecf787a Mon Sep 17 00:00:00 2001 From: Bryann Valderrama Date: Fri, 30 May 2025 12:00:48 -0500 Subject: [PATCH 1/3] docs: add migration path for legacy mechanisms ADR --- ...5-migration-path-for-legacy-mechanisms.rst | 83 +++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 docs/decisions/0005-migration-path-for-legacy-mechanisms.rst diff --git a/docs/decisions/0005-migration-path-for-legacy-mechanisms.rst b/docs/decisions/0005-migration-path-for-legacy-mechanisms.rst new file mode 100644 index 0000000..a0bc758 --- /dev/null +++ b/docs/decisions/0005-migration-path-for-legacy-mechanisms.rst @@ -0,0 +1,83 @@ +5. Migration Path for Legacy Mechanisms +####################################### + +Status +****** + +**Draft** - 2025-06-03 + +Context +******* + +Open edX currently uses several user grouping mechanisms (Cohorts, Teams, +Enrollment Tracks), each with its own logic, storage, and integration points. +This fragmentation: + +- Complicates maintenance and evolution. +- Makes it difficult to implement new functionality. +- Limits interoperability and extensibility. + +Two migration paths were evaluated to transition to a unified grouping system: + +- **Cross-System Synchronization**: creates an abstraction layer that + translates the new model to the legacy mechanisms. +- **Behavior Replication**: builds a new and independent system that replicates + the observable behavior of the legacy mechanisms without integrating with + them. + +Decision +******** + +- The behavior replication path was selected, removing direct dependencies on + the legacy systems. +- The new system does not synchronize with Cohorts, Teams, or Enrollment Tracks. +- Existing functionalities will be internally replicated within the new model. +- Migration will be carried out in clear and isolated phases to reduce risk. +- Activation will be controlled via feature flags, configurable by course, + organization, or platform. + +Consequences +************ + +- The new system can evolve with greater technical freedom. +- The responsibility for replicating legacy behavior lies entirely within the + new model, which must be thoroughly validated. +- The transition can be carried out gradually, implementing one functionality + at a time, allowing individual behavior validation and more targeted testing. + +Rejected Alternatives +********************* + +Cross-System Synchronization via an Abstraction Layer +===================================================== + +This proposal involved creating a new unified model while maintaining indirect +synchronization with the legacy mechanisms through an abstraction layer. This +layer would be responsible for: + +- Translating the logic of the new system to Cohorts, Teams, and Tracks. +- Ensuring backward compatibility during the entire transition. +- Enabling a gradual adoption while maintaining functional consistency with the + legacy systems. + +Reasons it was rejected: + +- Significant increase in technical complexity: maintaining bi-directional + synchronization between two systems introduces risk of errors, logic + duplication, and hard-to-debug issues. +- Higher maintenance cost: any change in the platform or legacy models would + also require updating the synchronization layer. +- Interference with the evolution of the new model: depending on legacy systems + limits the ability of the new system to introduce more flexible criteria or + rules. +- Greater difficulty in isolating and testing the new system: requiring the + presence of legacy systems makes independent validation of the new model more + complex. +- Legacy cleanup becomes harder: as long as active synchronization exists, + legacy code cannot be removed without breaking dependencies. + +References +********** + +- `Cross-System Synchronization Proposal `_ +- `Behavior Replication Proposal `_ From d4ac93f73aa027202a5267f4fed11593773f75b0 Mon Sep 17 00:00:00 2001 From: Bryann Valderrama Date: Tue, 3 Jun 2025 12:57:26 -0500 Subject: [PATCH 2/3] docs: update title and improve decision and consequences section --- ...5-migration-path-for-legacy-mechanisms.rst | 42 ++++++++++++------- 1 file changed, 27 insertions(+), 15 deletions(-) diff --git a/docs/decisions/0005-migration-path-for-legacy-mechanisms.rst b/docs/decisions/0005-migration-path-for-legacy-mechanisms.rst index a0bc758..3a4fcf6 100644 --- a/docs/decisions/0005-migration-path-for-legacy-mechanisms.rst +++ b/docs/decisions/0005-migration-path-for-legacy-mechanisms.rst @@ -1,5 +1,5 @@ -5. Migration Path for Legacy Mechanisms -####################################### +5. Migration Path for Legacy User Grouping Mechanisms +##################################################### Status ****** @@ -10,8 +10,8 @@ Context ******* Open edX currently uses several user grouping mechanisms (Cohorts, Teams, -Enrollment Tracks), each with its own logic, storage, and integration points. -This fragmentation: +Enrollment Track Groups), each with its own logic, storage, and integration +points. This fragmentation results in: - Complicates maintenance and evolution. - Makes it difficult to implement new functionality. @@ -28,34 +28,46 @@ Two migration paths were evaluated to transition to a unified grouping system: Decision ******** -- The behavior replication path was selected, removing direct dependencies on - the legacy systems. -- The new system does not synchronize with Cohorts, Teams, or Enrollment Tracks. -- Existing functionalities will be internally replicated within the new model. -- Migration will be carried out in clear and isolated phases to reduce risk. -- Activation will be controlled via feature flags, configurable by course, - organization, or platform. +We select the behavior replication approach, eliminating direct dependencies on +legacy systems. This choice enables a simpler, cleaner architecture with: + +- Full independence from legacy mechanisms from day one. +- Elimination of complex synchronization or integration layers. +- Reduced technical debt and maintenance costs during migration. + +Existing user-facing functionalities will be replicated in the new model, with +migration executed in clear, isolated phases to minimize risk. Activation will +be controlled via feature flags, configurable per course, organization, or +platform. + +See `ADR 6 `_ +for detailed rationale. Consequences ************ -- The new system can evolve with greater technical freedom. +- The new system can evolve independently, allowing greater flexibility. - The responsibility for replicating legacy behavior lies entirely within the new model, which must be thoroughly validated. - The transition can be carried out gradually, implementing one functionality at a time, allowing individual behavior validation and more targeted testing. +- Both new and legacy systems can coexist during rollout, avoiding user + disruption. +- Legacy systems will be fully deprecated and removed post-transition, + improving maintainability and extensibility. Rejected Alternatives ********************* -Cross-System Synchronization via an Abstraction Layer -===================================================== +Cross-System Synchronization +============================ This proposal involved creating a new unified model while maintaining indirect synchronization with the legacy mechanisms through an abstraction layer. This layer would be responsible for: -- Translating the logic of the new system to Cohorts, Teams, and Tracks. +- Translating the logic of the new system to Cohorts, Teams, and Enrollment + Track Groups. - Ensuring backward compatibility during the entire transition. - Enabling a gradual adoption while maintaining functional consistency with the legacy systems. From 3538ade25c633bde262168a7e022ee16cbc29499 Mon Sep 17 00:00:00 2001 From: Bryann Valderrama Date: Mon, 14 Jul 2025 12:10:01 -0500 Subject: [PATCH 3/3] chore: address PR review docs: refine language for clarity and consistency docs: update title format docs: include more detailed descriptions in each migration path docs: clarify proposal details in rejected alternatives docs: update legacy mechanism names docs: enhance migration path details for legacy mechanisms docs: expand synchronization strategy for legacy mechanisms in migration path docs: add comparison summary for migration strategies docs: clarify responsibilities for transitioning from legacy mechanisms --- ...5-migration-path-for-legacy-mechanisms.rst | 121 ++++++++++-------- 1 file changed, 66 insertions(+), 55 deletions(-) diff --git a/docs/decisions/0005-migration-path-for-legacy-mechanisms.rst b/docs/decisions/0005-migration-path-for-legacy-mechanisms.rst index 3a4fcf6..dc523f5 100644 --- a/docs/decisions/0005-migration-path-for-legacy-mechanisms.rst +++ b/docs/decisions/0005-migration-path-for-legacy-mechanisms.rst @@ -1,5 +1,5 @@ -5. Migration Path for Legacy User Grouping Mechanisms -##################################################### +0005. Migration Path for Legacy User Grouping Mechanisms +######################################################## Status ****** @@ -9,52 +9,44 @@ Status Context ******* -Open edX currently uses several user grouping mechanisms (Cohorts, Teams, -Enrollment Track Groups), each with its own logic, storage, and integration -points. This fragmentation results in: +Open edX currently uses several user grouping mechanisms (cohorts, teams, course groups), each with its own data models, business logic, storage, and integration points. This fragmentation results in: -- Complicates maintenance and evolution. -- Makes it difficult to implement new functionality. -- Limits interoperability and extensibility. +- Maintenance and evolution complications. +- New functionality implementation difficulties. +- Interoperability and extensibility limitations. -Two migration paths were evaluated to transition to a unified grouping system: +These legacy mechanisms were not designed for reuse across contexts such as messaging, analytics, or advanced segmentation, and lack support for dynamic grouping based on user attributes or behavior. -- **Cross-System Synchronization**: creates an abstraction layer that - translates the new model to the legacy mechanisms. -- **Behavior Replication**: builds a new and independent system that replicates - the observable behavior of the legacy mechanisms without integrating with - them. +To address these limitations, we proposed a **unified user grouping model**, as described in `ADR 2 <0002-user-groups-model-foundations.rst>`_, with a standardized structure that supports both static and dynamic groups, scoped at the course, organization, or platform level. Unlike legacy mechanisms, this unified system allows flexible group definitions and enables modular extensibility. It decouples user groups from specific platform features and enables reuse across diverse contexts (content gating, discussions, analytics, messaging, etc.). + +To migrate from the legacy mechanisms to this new model, two paths were evaluated: + +- **Cross-System Synchronization**: Introduces an abstraction layer that continuously translates the new model's state into the legacy mechanisms. This enables the new model to act as a central source while preserving backward compatibility by updating legacy structures in real time. +- **Behavior Replication**: Builds the new unified and independent grouping system that directly replicates the observable behavior of the legacy mechanisms within its own logic. Instead of integrating with or updating legacy mechanisms, it reproduces their functionality internally and gradually replaces them without requiring active synchronization. + +The key difference between these two strategies lies in how they relate to the legacy mechanisms, which in turn affects the complexity of the migration process, the technical debt incurred, and the long-term maintainability of the grouping architecture. Decision ******** -We select the behavior replication approach, eliminating direct dependencies on -legacy systems. This choice enables a simpler, cleaner architecture with: +We select the behavior replication approach, eliminating direct dependencies on legacy mechanisms. This choice enables a simpler, cleaner architecture with: - Full independence from legacy mechanisms from day one. - Elimination of complex synchronization or integration layers. - Reduced technical debt and maintenance costs during migration. -Existing user-facing functionalities will be replicated in the new model, with -migration executed in clear, isolated phases to minimize risk. Activation will -be controlled via feature flags, configurable per course, organization, or -platform. +Existing user-facing functionalities will be replicated in the new model with migration executed in clear, isolated phases to minimize risk. Activation will be controlled via feature flags, configurable per course, organization, or platform. -See `ADR 6 `_ -for detailed rationale. +See `ADR 6 <0006-replication-of-legacy-mechanisms-behavior.rst>`_ for detailed rationale. Consequences ************ - The new system can evolve independently, allowing greater flexibility. -- The responsibility for replicating legacy behavior lies entirely within the - new model, which must be thoroughly validated. -- The transition can be carried out gradually, implementing one functionality - at a time, allowing individual behavior validation and more targeted testing. -- Both new and legacy systems can coexist during rollout, avoiding user - disruption. -- Legacy systems will be fully deprecated and removed post-transition, - improving maintainability and extensibility. +- The responsibility for replicating legacy behavior lies entirely within the new model, which must be thoroughly validated. +- The transition can be carried out gradually, implementing one functionality at a time, allowing individual behavior validation and more targeted testing. +- Both new and legacy mechanisms can coexist during rollout, avoiding user disruption. +- Legacy mechanisms will be fully deprecated and removed post-transition, improving maintainability and extensibility. Courses that still rely on legacy grouping systems at the time of removal will not be automatically migrated. It will be the responsibility of course authors or site operators to manually transition their configurations to the new system before deprecation occurs. Failure to do so may result in the loss of grouping data or functionality associated with cohorts, teams, or enrollment track groups. Rejected Alternatives ********************* @@ -62,31 +54,50 @@ Rejected Alternatives Cross-System Synchronization ============================ -This proposal involved creating a new unified model while maintaining indirect -synchronization with the legacy mechanisms through an abstraction layer. This -layer would be responsible for: - -- Translating the logic of the new system to Cohorts, Teams, and Enrollment - Track Groups. -- Ensuring backward compatibility during the entire transition. -- Enabling a gradual adoption while maintaining functional consistency with the - legacy systems. - -Reasons it was rejected: - -- Significant increase in technical complexity: maintaining bi-directional - synchronization between two systems introduces risk of errors, logic - duplication, and hard-to-debug issues. -- Higher maintenance cost: any change in the platform or legacy models would - also require updating the synchronization layer. -- Interference with the evolution of the new model: depending on legacy systems - limits the ability of the new system to introduce more flexible criteria or - rules. -- Greater difficulty in isolating and testing the new system: requiring the - presence of legacy systems makes independent validation of the new model more - complex. -- Legacy cleanup becomes harder: as long as active synchronization exists, - legacy code cannot be removed without breaking dependencies. +This approach, like the selected one, builds on top of the new unified grouping system. However, it differs in that it maintains indirect synchronization with the legacy mechanisms through an abstraction layer. + +The synchronization strategy involves monitoring changes in either system (new or legacy), interpreting those changes through registered evaluators, and propagating updates to maintain alignment. This ensures both systems reflect a consistent state, at the cost of added runtime logic and maintenance overhead. + +This layer would be responsible for: + +- **Translating the logic of the new system to legacy mechanisms**: Establishing a bi-directional synchronization layer that ensures both systems remain consistent. This abstraction layer would monitor changes in the unified model, such as group creation, updates to membership, or criteria changes. It would then propagate these changes to the corresponding legacy mechanisms. + + Likewise, any modifications in the legacy mechanisms would also need to be captured and reflected back in the new model to maintain alignment. This translation mechanism would allow legacy features (e.g., content gating, discussions, ORA assignments) to continue operating using their existing infrastructure. They would be effectively controlled by the unified model behind the scenes. + +- **Ensuring backward compatibility during the entire transition**: The platform must preserve full functional integrity of the legacy grouping mechanisms (cohorts, teams, course groups) while the new model is introduced. The abstraction layer would need to convert the unified model's definitions into updates to legacy models and APIs. This ensures that existing behaviors remain unchanged for instructors, learners, and third-party integrations. + +- **Enabling gradual adoption while maintaining functional consistency**: Migrate to the new grouping model incrementally, activating it course-by-course or organization-wide using feature flags. During this phased adoption, the abstraction layer ensures both models can operate in parallel without conflict. This allows selective rollout, targeted validation, and fallback to legacy behavior if needed. All while maintaining consistent user experience and platform behavior. + +Reasons for rejection: + +- **Significant increase in technical complexity**: Maintaining bi-directional synchronization between two systems introduces risk of errors, logic duplication, and hard-to-debug issues. +- **Higher maintenance cost**: Any change in the platform or legacy models would also require updating the synchronization layer. +- **Interference with the evolution of the new model**: Depending on legacy mechanisms limits the ability of the new system to introduce more flexible criteria or rules. +- **Greater difficulty in isolating and testing the new system**: Requiring the presence of legacy mechanisms makes independent validation of the new model more complex. +- **Legacy cleanup becomes harder**: As long as active synchronization exists, legacy code cannot be removed without breaking dependencies. + +Comparison Summary +------------------ + +The following table summarizes the key differences between the two migration strategies: + ++-----------------------------+----------------------------------------------+------------------------------------------------+ +| Aspect | Cross-System Synchronization | Behavior Replication | ++=============================+==============================================+================================================+ +| Legacy Dependency | Requires maintaining legacy systems | No dependency on legacy systems | ++-----------------------------+----------------------------------------------+------------------------------------------------+ +| Synchronization Complexity | High: requires bi-directional sync layer | None: new system operates independently | ++-----------------------------+----------------------------------------------+------------------------------------------------+ +| Backward Compatibility | Full, via real-time updates to legacy state | Achieved by replicating observable behaviors | ++-----------------------------+----------------------------------------------+------------------------------------------------+ +| Testing & Validation | Difficult: both systems must stay in sync | Easier: new model can be tested in isolation | ++-----------------------------+----------------------------------------------+------------------------------------------------+ +| Migration Strategy | Gradual, but tightly coupled with legacy | Gradual, with clean separation | ++-----------------------------+----------------------------------------------+------------------------------------------------+ +| Long-Term Maintenance | Higher effort due to dual-system complexity | Lower effort after transition is complete | ++-----------------------------+----------------------------------------------+------------------------------------------------+ +| Time to Legacy Removal | Longer: active sync delays removal | Shorter: legacy can be phased out per feature | ++-----------------------------+----------------------------------------------+------------------------------------------------+ References **********