docs: add arch decision record for the migration path for legacy user grouping mechanisms

[BryanttV]

Description

This PR adds an Architecture Decision Record (ADR) documenting the selected migration path for replacing legacy user grouping mechanisms in Open edX (Cohorts, Teams, and Enrollment Track Groups).

This ADR defines the migration strategy based on behavior replication, while this ADR describes the plan to implement that strategy in phases.

Related ADRs

• docs: add arch decision record for the replication-based migration of legacy user grouping mechanisms #5

Supported Information

https://openedx.atlassian.net/wiki/spaces/OEPM/pages/4901404678/User+Groups

[openedx-webhooks]

Thanks for the pull request, @BryanttV!

This repository is currently maintained by @openedx/committers-user-groups.

Once you've gone through the following steps feel free to tag them in a comment and let them know that your changes are ready for engineering review.

🔘 Get product approval

If you haven't already, check this list to see if your contribution needs to go through the product review process.

• If it does, you'll need to submit a product proposal for your contribution, and have it reviewed by the Product Working Group.
  • This process (including the steps you'll need to take) is documented here.
• If it doesn't, simply proceed with the next step.

🔘 Provide context

To help your reviewers and other members of the community understand the purpose and larger context of your changes, feel free to add as much of the following information to the PR description as you can:

• Dependencies

  This PR must be merged before / after / at the same time as ...

• Blockers

  This PR is waiting for OEP-1234 to be accepted.

• Timeline information

  This PR must be merged by XX date because ...

• Partner information

  This is for a course on edx.org.

• Supporting documentation
• Relevant Open edX discussion forum threads

🔘 Get a green build

If one or more checks are failing, continue working on your changes until this is no longer the case and your build turns green.

---

Where can I find more information?

If you'd like to get more details on all aspects of the review process for open source pull requests (OSPRs), check out the following resources:

• Overview of Review Process for Community Contributions
• Pull Request Status Guide
• Making changes to your pull request

When can I expect my changes to be merged?

Our goal is to get community contributions seen and reviewed as efficiently as possible.

However, the amount of time that it takes to review and merge a PR can vary significantly based on factors such as:

• The size and impact of the changes that it introduces
• The need for product review
• Maintenance status of the parent repository

💡 As a result it may take up to several weeks or months to complete a review and merge your PR.

[mariajgrimaldi]

In both cases we're building a new system. I think the main difference here is how we intend to use them, through a connecting layer or using the new model directly. I think I'd also prefer to have more details as in the technical docs we produced.

[BryanttV]

Thanks! I included more details about both migration paths. Do you think we should include anything else?

[mariajgrimaldi]

Should we specify that both approaches build on top of the new model but the difference is how they relate with legacy systems?

[BryanttV]

I agree! I updated the description according to your suggestion.

[mariajgrimaldi]

What does it mean translating the new logic in this context? Can we add more details as in https://openedx.atlassian.net/wiki/spaces/OEPM/pages/4955668482/Cross-System+Synchronization+Proposal?atlOrigin=eyJpIjoiMWE2NTgxNGE0NDEzNGE2YmI2ODgyNTI2ZTBiNTc0NmUiLCJwIjoiYyJ9 so folks understand why we're rejecting it?

[BryanttV]

Thanks for noticing! I added more details about what it means to translate the logic into the new system.

[mariajgrimaldi]

It'd be useful to add the following in this context section as context on how we got here -these are only some ideas that should be refined before including them-:

• We've proposed a unified model with X, Y, Z structure that differentiates from the legacy in W, ...
• This model must be able to replace the legacy models... and to do so, then this should happen... (support and behavior)
• By unifying all these into a single model, we gain... so we propose migrating all legacy mechanisms gradually to this new unified model
• The main difference in the approaches considered is how they relate to legacy mechanisms, which also affect the deprecation strategy and long-term maintainability...

[BryanttV]

Thanks for your suggestions! I updated the section to provide a bit more context. What do you think?

[mariajgrimaldi]

Another rejected decision was maintaining both the new model and legacy, I think.

[BryanttV]

That alternative wasn’t documented. Do you think we should include it as a rejected option as well? I can add a brief explanation of why it was not chosen.

[mariajgrimaldi]

We didn't explain what the approach is about to mention the bi-directional sync, should we? I think we also should mention the synchronization strategy, so folks understand the complexity.

[BryanttV]

Thanks! I included details about what the synchronization strategy is to provide more clarity.

[mariajgrimaldi]

Should we compare the two as we did in the technical document? https://openedx.atlassian.net/wiki/spaces/OEPM/pages/5014192131/Migration+Path+Proposals+from+Legacy+to+the+Unified+Model#Comparative-Table

[BryanttV]

I agree! I included the comparative table.

[bmtcril]

I think we should include more information here on what will happen to any running courses that are still using the old systems when the deprecation lands. Will we force migrate them?

[BryanttV]

Thanks for the suggestion! I've clarified that courses still using legacy grouping systems at the time of deprecation will not be automatically migrated. It will be up to course authors or site operators to transition their configurations manually. If no action is taken, they may lose access to grouping data or functionality related to cohorts, teams, or enrollment track groups.

[bmtcril]

It may be useful to say that feature flags can allow running courses to finish with the legacy mechanism in the upgrade window, potentially cutting down on the problems of gated content grading and related issues. We may want to have an extended (2 release?) window of co-existence and a command to automatically exempt running courses that are using the legacy features at the feature flag level. What do you think? @BryanttV @mariajgrimaldi

[kdmccormick]

I think it would be a mistake to break backwards compatibility with existing content without an automated migration. We have historically taken backwards compatibility of OLX very seriously, even while making major architectural changes like the XModule -> XBlock migration, the switch from the legacy courseware view to the Learning MFE, and the ongoing ModuleStore -> Learning Core migration. In each of those projects, we automatically migrated as much as we could, and then did our best to clearly announce each breaking change that we couldn't handle in the migration. I think the User Groups project should take the same approach.

[kdmccormick]

Stepping back: the lack of automatic migration jumped out at me in my first pass through these ADRs, but I think I focused too much on that. Let me reframe.

I'm currently trying to understand which legacy grouping mechanisms this will replace, and it which ones it'll coexsit alongside in the long term. These are the grouping mechanisms I'm familiar with:

• Content Groups a.k.a. UserPartition Groups -- This allows XBlocks to restrict their access to a set of with numerically-identified Groups, where each Group is a division of a numerically-identified UserPartition, where a UserPartition represents the abstract notion of dividing learners by some pluggable criteria (e.g. cohorting, teaming, enrollment track, etc.). In order to remain compatible with re-running and import/export, these Groups are not mapped to users or any other LMS-specific concept; instead, the XBlock-Group associations are published without any user information, and then the courseware runtime maps the Groups to concrete LMS things like Cohorts, Teams, Enrollment Tracks, etc.
• Cohorts a.k.a. CourseGroups -- These are configured in the LMS. When enabled in a course, a UserParition is created for the cohorting feature, and each Cohort (CourseGroup) is mapped to one or more Content Group (UserPartitionGroup).
• Teams -- Teamsets are configured in course settings (and persisted in OLX), and each teamset's teams are populated in the LMS by instructors or the users themselves, depending on the type of teamset. There is a beta flag (CONTENT_GROUPS_FOR_TEAMS) which, when enabled, allows each Teamset to function as a UserPartition and each Team to function as a UserPartitionGroup (but this violates the "no-LMS-data-in-UserPartitionGroups" principle I mentioned earlier, and I think we'll need to retroactively add some indirection there before globally enabling that flag).
• Course Access Roles (instructor, TA, etc.) -- This is more about RBAC than about user grouping, but I bring it up because it sounds like UserGroups could include staff groups.

My main compatibility concern is around UserPartitionGroups. This system is baked into the modulestore records and OLX of every existing course, so I don't see breaking it as an option. That said, I'm eager to improve it and help make sure it works with UserGroups, and based on the POC Ty shared with me, it seems like you all are already aware of this system and have ideas of how to integrate it with UserPartitionGroups.

I'll keep studying these ADRs in the POC. In the meantime, I'll ask: are you thinking the the UserGroups system will be an umbrella which includes UserPartitioning feature, or are you thinking of UserGroups as the LMS system which is a counterpart to UserPartitioning? Or something else entirely?