Merge pull request #22914 from cpennington/rel-dates-adr

Add ADR for relative courseware dates

lms/djangoapps/courseware/docs/decisions/0004-personalized-relative-dates.rst

+0004. Personalized/Relative Dates in Courseware
+***********************************************
+
+~~~~~~~
+Context
+~~~~~~~
+
+Self-paced courses are, based on the experience of users on edx.org,
+less engaging and less likely to be completed, than instructor-paced courses.
+Research shows that learners are better able to complete a course of study
+when that course gives them multiple incremental deadlines along the way,
+rather than one single deadline at the end of the course. Unfortunately,
+self-paced courses are currently only able to offer the latter experience.
+
+``edx-when`` is a library currently used by ``edx-platform`` to provide a
+read-optimized view of the dates associated with course content. It is updated
+when a course is published, and stores dates in a dedicated table in the
+relational database.
+
+~~~~~~~~~~~
+Definitions
+~~~~~~~~~~~
+
+Absolute date:
+    A date and time, represented in python as `datetime.datetime`.
+Relative date:
+    A date and time offset, represented in python as `datetime.timedelta`.
+    To convert to an Absolute date, the offset is added to a students Content
+    Availability Date.
+Content Availability Date:
+    The students enrollment date, or the course start date, whichever is later.
+
+~~~~~~~~
+Decision
+~~~~~~~~
+
+In order to support incremental deadlines in self-paced courses, we want
+to extend edx-platform with the following capabilities:
+
+1.  Extend the api provided by ``edx-when`` used in the LMS to so that
+    the LMS can ask for dates for students (supplying their ``Schedule``), and
+    ``edx-when`` will return an absolute date (even if the date defined by
+    Studio is relative).
+2.  When a self-paced course is published, add relative due dates to it,
+    evenly spaced across the expected duration of the course, unless the
+    course already has relative dates attached to content.
+
+    a.  These dates should be pushed into ``edx-when``
+        by Studio. We will move the existing ``edx-when`` course-publish signal
+        handler out into Studio, and have it use exposed ``edx-when`` APIs to
+        write in absolute or relative dates.
+    b.  While there are no current plans to allow Studio authors to author
+        relative dates, by making the evenly-spacing only occur if there
+        is no existing relative dates on the course, we leave ourselves the
+        ability to add future studio authoring without changing ``edx-when``.
+    c.  Adding the relative dates on course-publish, and storing them in ``edx-when``,
+        rather than inferring them at run-time while reading from ``edx-when``
+        means that we have the course structure in-hand (from the course
+        publish), and that ``edx-when`` will remain a full listing of all dates
+        in the course. If, instead, the LMS inferred relative dates when they
+        weren't set in ``edx-when``, then new date-based functionality in the
+        future would need to either read through a specific api that would
+        inject the programmatic dates, or would have to infer its own dates.
+3.  No new fields would be added to XBlocks at this time to represent relative
+    dates. There is no studio authoring component for this feature, and the LMS
+    Xblock runtime would contextualize relative dates for a specific student
+    when supplying them to XBlock fields.
+4.  Update the documentation in ``edx-when`` to capture our current
+    understanding of its responsibilities. To wit, ``edx-when`` exists to give
+    the LMS a single place to ask "What does this student have coming up,
+    across one or many courses?", and get a fast, efficient answer. To that
+    end, the ``schedules`` django app should be moved into ``edx-when``, and
+    it will handle any future features related to the ability to scale pacing
+    in self-paced courses faster or slower. ``edx-when`` is thus both a
+    performance optimization(because it is optimized for reading), and the
+    single dedicated owner of a particular user's schedule of course content.
+
+    However, it does not include information about course-level administrative
+    dates, such as the upgrade deadline, so that will need to be disentangled
+    from the Schedule model (or we'll need to expand ``edx-when`` with
+    additional notions of date semantics).
+5.  ``edx-when``, and the ``schedules`` app, should keep history, so that we
+    can determine at analysis time what their schedule was when they answered
+    a problem. Using a simple history table should be sufficient to also
+    support showing a user the history of changes to their own schedule.
+
+~~~~~~
+Status
+~~~~~~
+
+Proposed
+
+~~~~~~~~~~~~
+Consequences
+~~~~~~~~~~~~
+
+Once implemented, self-paced courses in the LMS would begin to have
+due dates for course content that are consistent between users, but that
+are personalized based on when a user started a course. We would be open
+to exploring future functionality for allowing users to adjust their schedule
+by resetting their effective course start time, or speeding up or slowing
+down their pacing.
+
+~~~~~~~~~~~~~~~~~~~~~
+Rejected Alternatives
+~~~~~~~~~~~~~~~~~~~~~
+
+Expand Capabilities of XBlock DateField
+---------------------------------------
+
+It's tempting to allow the XBlock DateField to support relative dates as well
+as absolute dates. However, that would cause OLX backwards incompatibility
+when the relative dates were exported into the same field as the existing
+absolute dates.
+
+Offset From Previous Content
+----------------------------
+
+Rather than considering date offsets to be relative to the start of the users
+schedule, maybe they should be relative to the previous item of content.
+That way, when you reset a schedule (or change a users pacing), you can just
+modify future content.
+
+The difficulties with this proposal are:
+
+1.  In order to find the actual absolute date of a piece of content, you need
+    to access all of the content before that item in the course, and then
+    sum up all of their offsets. This makes it harder to easily query all
+    upcoming due-dates over multiple courses.
+2.  When a user resets their schedule, they probably want to adjust previous
+    dates as well, so that they can go back and answer problems that they
+    missed. If that's the case, then adjusting the start date based on the
+    newly requested extension will make it easier update old and new content
+    consistently.
+