diff --git a/docs/openedx_learning/decisions/0005-pathway-and-pathway-items.rst b/docs/openedx_learning/decisions/0005-pathway-and-pathway-items.rst new file mode 100644 index 000000000..3d7c587b0 --- /dev/null +++ b/docs/openedx_learning/decisions/0005-pathway-and-pathway-items.rst @@ -0,0 +1,62 @@ +.. _openedx-learning-adr-0005: + +5. Pathways: The Boundary Between Pathway and Pathway Item +========================================================== + +Status +------ + +Draft + +Context +------- + +A Pathway is a set of requirements that a learner works through to earn some larger achievement, such as a +certificate. Each requirement is represented by a **Pathway Item**. We want to draw the boundary between these two +concepts so that the Pathway level stays stable while the Item level - and especially the ways Items get fulfilled - +can evolve. + +Decisions +--------- + +1. A Pathway holds an ordered list of Pathway Items. The order is author-defined and is the order in which Items are + presented to learners. In the future, we plan to also support enforcing the order of completion. + +2. A Pathway Item has its own identity and lifecycle. An Item may be fulfilled by one thing today (e.g. passing a + course) and by something else tomorrow (e.g. a competency attainment, or an admin override) without changing its + identity - and therefore without changing the Pathway that contains it. How fulfillment is modeled is a separate + decision (:ref:`openedx-learning-adr-0006`). + +3. Pathway to Item relationships do not break new ground structurally. We already have precedent for modeling + parent-child relations in ``openedx_content`` containers; Pathway/PathwayItem will not use Container directly, + as they don't need Container's full complexity. + +4. **Item completion and Pathway completion are separate concerns.** An Item is complete or not, determined by its own + fulfillment rules; the Pathway's completion is computed from Item completion. + +5. In the MVP, Pathway completion is not configurable: a Pathway is complete when *all* of its Items are complete. + Because every Item is fulfilled by passing a course (:ref:`openedx-learning-adr-0006`), this means the learner has + passed every course in the Pathway, with grade and passed/failed state read directly from each course. Configurable + criteria (e.g. "complete 4 of these 5 Items") are expected in later iterations, and the intent is for them to be + expressed in terms of Item completion rather than the Pathway-specific definition of what fulfills each Item. + +6. The Item completion contract is deliberately minimal for now - complete or not. It can be extended later to carry + grades or other metadata, if more complex Pathway-level criteria or learner-facing displays need it. + +.. Run `dot -Tsvg images/pathway-and-items.dot > images/pathway-and-items.svg` to regenerate the diagram after making + changes to `images/pathway-and-items.dot`. + +.. image:: images/pathway-and-items.svg + :alt: Pathway, Pathway Items, and the fulfillment boundary + :width: 100% + +Consequences +------------ + +- New ways of fulfilling Items can be introduced without restructuring Pathways or rewriting how Pathway completion + is computed. +- Learner-facing progress ("3 of 6 Items complete") is computed from Item completion, so it also remains stable + across such changes. +- Interventions like admin overrides act on Item completion and are automatically respected by Pathway completion. +- Extending the Item completion contract beyond a yes/no is an additive change, so nothing here has to be revisited + to do it. diff --git a/docs/openedx_learning/decisions/images/pathway-and-items.dot b/docs/openedx_learning/decisions/images/pathway-and-items.dot new file mode 100644 index 000000000..475845d8e --- /dev/null +++ b/docs/openedx_learning/decisions/images/pathway-and-items.dot @@ -0,0 +1,34 @@ +digraph pathway_and_items { + rankdir=LR; + fontname="Helvetica"; + node [shape=box, style=rounded, fontname="Helvetica", fontsize=11]; + edge [fontname="Helvetica", fontsize=10]; + + pathway [label="Pathway\nMVP completion:\nall Items complete"]; + + subgraph cluster_items { + label="Pathway Items (ordered)"; + fontsize=10; + fontcolor="#4d4d4d"; + style=dashed; + color="#b3b3b3"; + item1 [label="Item 1"]; + item2 [label="Item 2"]; + item3 [label="Item 3"]; + item1 -> item2 -> item3 [style=dotted, arrowsize=0.7, color="#808080", constraint=false]; + {rank=same; item1; item2; item3;} + } + + fulfill [label="things that fulfill Items\n(courses today;\nsections, competencies,\nadmin overrides later)", style="rounded,dashed"]; + + pathway -> item1 [label="reads completion"]; + pathway -> item2; + pathway -> item3; + + item1 -> fulfill [style=dashed]; + item2 -> fulfill [style=dashed]; + item3 -> fulfill [style=dashed]; + + boundary [label="Pathway completion is computed from Item completion;\nit does not reach into what fulfills each Item", shape=plaintext, fontsize=10, fontcolor="#4d4d4d"]; + {rank=same; pathway; boundary;} +} diff --git a/docs/openedx_learning/decisions/images/pathway-and-items.svg b/docs/openedx_learning/decisions/images/pathway-and-items.svg new file mode 100644 index 000000000..071cd9824 --- /dev/null +++ b/docs/openedx_learning/decisions/images/pathway-and-items.svg @@ -0,0 +1,108 @@ + + + + + + +pathway_and_items + + +cluster_items + +Pathway Items (ordered) + + + +pathway + +Pathway +MVP completion: +all Items complete + + + +item1 + +Item 1 + + + +pathway->item1 + + +reads completion + + + +item2 + +Item 2 + + + +pathway->item2 + + + + + +item3 + +Item 3 + + + +pathway->item3 + + + + + +item1->item2 + + + + + +fulfill + +things that fulfill Items +(courses today; +sections, competencies, +admin overrides later) + + + +item1->fulfill + + + + + +item2->item3 + + + + + +item2->fulfill + + + + + +item3->fulfill + + + + + +boundary +Pathway completion is computed from Item completion; +it does not reach into what fulfills each Item + + +