From 9966b78e4953e2eefb78aef4f023f813de239281 Mon Sep 17 00:00:00 2001 From: Feanil Patel Date: Wed, 31 Jan 2024 14:44:40 -0500 Subject: [PATCH 1/2] docs: ADR for an edx-platform representation of Catalog Courses. Summary; We should have a way to model the associations between multiple course runs that are all for the same logical course. This model should be a part of the core edx-platform models but should integrate seamlessly with course-discovery where it makes sense. See the ADR for more details. --- .../docs/decisions/002-course-models.rst | 76 +++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 openedx/core/djangoapps/catalog/docs/decisions/002-course-models.rst diff --git a/openedx/core/djangoapps/catalog/docs/decisions/002-course-models.rst b/openedx/core/djangoapps/catalog/docs/decisions/002-course-models.rst new file mode 100644 index 000000000000..ea862593ef82 --- /dev/null +++ b/openedx/core/djangoapps/catalog/docs/decisions/002-course-models.rst @@ -0,0 +1,76 @@ +Course Models +############# + +Status +****** + +Accepted + +Decision +******** + +edx-platform will have a first-class model to represent the idea of a catalog +course. If we think of multiple runs of the same course to all derive from one +conceptiual course. The catalog course would be that conceptual course. + +Context +******* + +Historically this concept has been inferred from the names of courses with the +runs removed (eg. "AximX/Eng101" could be a catalog course with multiple runs +(2024H1, 2024H2, etc)). Having this explicitly defined as a new model has +multiple benefits. + +* Relationships between course runs can be defined explicitly instead of implicitly. + + * Currently this information is either implied or we require the entire + course-discovery service in order to retrieve this information. + +* A list of all courses can be easily queried both internally and via the rest API. + +* Courses can be explicitly mapped to organizations rather than implicitly. + +* This change opens up the door for program or course bundle data to be persisted +so that a reset of mem cache doesn't break programs related features. + +* Org → Course → Course Runs mappings don't have to follow implicit naming + Conventions and associations can be changed more easily. + +Rejected Alternatives +********************* + +Rely on course-discovery for CatalogCourse +========================================== + +The course-discovery service already has some models to represent this and we +could rely on it directly but it also contains a lot of representations that +are specific to the edx.org process and it's not valuable to spin up the +course-discovery service just to get this information for most operators. + +As long as any local data can be updated from course-discovery if +course-discovery is setup in an environment, we should not have any conflicts +between the two locations. + +Essentially, if an operator has course-discovery enabled, the models here would +essentially be a persisted cache of the relevant information. However, if +course-discovery is not enabled, the models can stand-alone and be populated +either directly via APIs or automatically based on course naming conventions so +that any features that rely on them can work in either system. + + +Implementation Details +********************** + +* Create a new CatalogCourse model + +* A 1:N mapping between 1 Catalog Course and N Course Overview objects. + +* A 1:N mapping between 1 Organization and N Catalog Course objects. + +* A django admin that allows you to View and Manipulate Catalog Course objects and their associations. + +* A data migration to make all current implicit associations explicit. + +* Eventing hooks to auto-associate new runs to their implicit Catalog Course + +* A REST api to CRUD Course Overview. Catalog Course, and Org data, along with their associations. From 41b4b0723784fb579acd86062027730b4cc28867 Mon Sep 17 00:00:00 2001 From: Feanil Patel Date: Tue, 6 Aug 2024 12:16:44 -0400 Subject: [PATCH 2/2] docs: Apply suggestions from code review Co-authored-by: Kyle McCormick --- .../docs/decisions/002-course-models.rst | 36 +++++++++++++------ 1 file changed, 25 insertions(+), 11 deletions(-) diff --git a/openedx/core/djangoapps/catalog/docs/decisions/002-course-models.rst b/openedx/core/djangoapps/catalog/docs/decisions/002-course-models.rst index ea862593ef82..d9457b6d5d6d 100644 --- a/openedx/core/djangoapps/catalog/docs/decisions/002-course-models.rst +++ b/openedx/core/djangoapps/catalog/docs/decisions/002-course-models.rst @@ -6,32 +6,44 @@ Status Accepted +Implementation pending + Decision ******** -edx-platform will have a first-class model to represent the idea of a catalog -course. If we think of multiple runs of the same course to all derive from one -conceptiual course. The catalog course would be that conceptual course. +edx-platform will have a first-class model to represent the idea of a *catalog course*. +If we think of multiple runs of the same course to all derive from one +conceptual "course", the catalog course is what will represent that conceptual course. Context ******* -Historically this concept has been inferred from the names of courses with the +The term "course" in Open edX is ambiguous, referring to one of two things: + +1. An individual *run* of a course which is authored in Studio and published to LMS. Here, we call this the **CourseRun**. In edx-platform, it is modeled by the **CourseOverview**. +2. A logical course *catalog* entry that may be marketed, sold, awarded as a credential, and bundled into programs. Here, we call this the **CatalogCourse**. + +Every one CatalogCourse maps to N CourseRuns. + +Historically, CatalogCourses have been inferred from the names of courses with the +runs removed (eg. `course-v1:AximX/Eng101` could be a catalog course with multiple runs +(`course-v1:AximX/Eng101:2024H1`, `course-v1:AximX/Eng1012024H2`, etc)). Having the catalog course explicitly defined as a new model has multiple benefits. runs removed (eg. "AximX/Eng101" could be a catalog course with multiple runs (2024H1, 2024H2, etc)). Having this explicitly defined as a new model has multiple benefits. * Relationships between course runs can be defined explicitly instead of implicitly. - * Currently this information is either implied or we require the entire - course-discovery service in order to retrieve this information. + * Currently this information is either implied (via course key) or requested from + course-discovery. In the case of edx-platform, it loads the entire course-discovery + database into a cache. * A list of all courses can be easily queried both internally and via the rest API. -* Courses can be explicitly mapped to organizations rather than implicitly. +* Catalog courses can be explicitly mapped to organizations rather than implicitly. -* This change opens up the door for program or course bundle data to be persisted -so that a reset of mem cache doesn't break programs related features. +* The door is opened to also persist program or course bundle data in the future. + This will stop `programs-related features from breaking whenever memcached is reset `_. * Org → Course → Course Runs mappings don't have to follow implicit naming Conventions and associations can be changed more easily. @@ -52,7 +64,7 @@ course-discovery is setup in an environment, we should not have any conflicts between the two locations. Essentially, if an operator has course-discovery enabled, the models here would -essentially be a persisted cache of the relevant information. However, if +be a persisted cache of the relevant information. However, if course-discovery is not enabled, the models can stand-alone and be populated either directly via APIs or automatically based on course naming conventions so that any features that rely on them can work in either system. @@ -63,7 +75,9 @@ Implementation Details * Create a new CatalogCourse model -* A 1:N mapping between 1 Catalog Course and N Course Overview objects. +* A 1:N mapping between 1 Catalog Course and N Course Run objects. + + * Open question: do we re-use CourseOverview to represent Course Run, or do we make a new CourseRun run model? * A 1:N mapping between 1 Organization and N Catalog Course objects.