Proposal for course revisioning strategy

Drupal Commerce has a similar need. When you buy a product, it should be frozen in time, and not subject to future edits. I’m not sure if they solve this by refusing. Worth a look.

In general this proposal makes sense to me. There are.a couple downsides. Namely teachers Can’t easily fix typos in a course and have that affect students in progress. Same for scoring. Also we could see revision bloat similar to what happens on sites that use paragraphs module.

@moshe weitzman thanks for the feedback, much appreciated.

The thinking is that for something like a typo, teachers/admins can submit an edit and not create a new revision, in which case the change will be pushed live to current students.

Revisions shouldn't proliferate too badly since it will be a conscious choice to make a new one, and we can implement processes to safely delete old unused revisions.

I'll check out the Commerce approach, thanks for that tip!

The thinking is that for something like a typo, teachers/admins can submit an edit and not create a new revision, in which case the change will be pushed live to current students.

I think this is a bit too subtle to expect course authors to understand the implications of or get right all the time even if they do - if you're just doing a quick fix, the default behaviour would be to fix the typo and hit save. Once revisions default to on, that will result in a new revision, you have to take extra steps to avoid it.

However the issue summary doesn't explicitly mention that e.g. lessons would reference specific versions of activities (which is the only way older versions could be loaded), and I'm not sure it's necessary.

If e.g. a lesson status references a specific revision of a lesson, then the list of activities will differ by version, and it's that which would allow activities to be added or removed from lessons without affecting students in progress.

Similar if a course status references a specific revision of a course, the list of lessons will differ by version.

https://www.drupal.org/project/entity_reference_revisions →

There's another issue though that something like adding a lesson at the end of a course where no-one has reached it yet, you might want everyone to take that lesson

We could make a global setting so the site owner can choose if students take the course / lesson versions from the moment of starting or current, that'd also solve any possible BC issues.

I think we could do phase 1 without the exact details of what phase 2/3 look like - we definitely want answers, lesson status, and course status to reference revisions. Means switching the entity reference field over to https://www.drupal.org/project/entity_reference_revisions →

Can we start off by adding *_vid fields to CourseStatus, LessonStatus, and Answer entities and run an initial update hook, then transition to Entity Reference Revisions when we're ready to migrate the Course.lessons and Lesson.activities fields? Seems like that could make the updates less monolithic.

Drupal Commerce has a similar need...I’m not sure if they solve this by revisions.

Turns out Commerce copies the current product data into an order item. Same need but not really a transferable solution.

I think [the revision checkbox] is a bit too subtle to expect course authors to understand the implications of or get right all the time even if they do

The revision checkbox could have explicit instructions marked "IMPORTANT". Or we could alter the form to have two submit buttons, one for a minor live update, the other for a new version. Either way I agree it's hard to make it foolproof. Needs good documentation.

something like adding a lesson at the end of a course where no-one has reached it yet, you might want everyone to take that lesson

The "Freshest Unaccessed Content" feature would address this. It adds some complexity to the lock-in timing, but seems worthwhile for long courses.

We could make a global setting so the site owner can choose if students take the course / lesson versions from the moment of starting or current

If set to "current" then we'd lose consistency with evaluation & revisits, unless we associate revision lists with uid. The revision schema updates add a BC layer, so not sure if this would add more complication than it's worth.

Just a “vid” field will not be enough, for example lesson status references multiple activities, that’d be too messy. I also wouldn’t like to add an additional dependency but we can use some of the Entity Reference Revisions code as a reference - a new field type plugin should be enough in our case.
Update may be a bit tricky.

Actually.. maybe it’s not going to be so bad as we’ll just need to add a new column to an existing schema, reference field names will not change after all.

This will be bigger as we'll have to reference lesson revisions from course status as we currently reference activities from lesson status. The good thing is consistency though. That should be the first step of the work here. The first step alone will only introduce needless data storage though.

This will also affect caching a lot - nav block will depend on course status lessons and not course lessons. Course nav structure cache will have to be dropped.

For #12 I think we might want to make this configurable so that you only get a per-course-status navigation structure/activity display when the site owner explicitly wants that - I can equally see people being confused why they can't fix a typo in an activity name for existing users.

Also we already have logic to cache the navigation block differently depending on whether modules are finished, in progress, or not taken yet so it should be possible to preserve some or most of that.

Added a draft MR, all seems to be working but still a lot of testing is needed and nav block cacheability needs to be updated.

One thing is very annoying: we need an update hook that converts the old field types to the new one, copies target_id data from the old tables and sets new data basing on current entity revisions. We can also make this feature available in the next major but still - it wouldn't be nice if we didn't provide an upgrade path.

I'm not any good with that, spend a lot of time on it already with highly unsatisfying results so.. If anyone wants to help or provide a good example from which I could just copy-paste some code, we can do it. Been there: https://www.drupal.org/docs/drupal-apis/update-api/updating-entities-and... → , https://www.drupal.org/project/field_type_converter →

If not - let's release that next major ASAP while we still don't have any or very little projects in production phase. Maintaining 2 branches will also be too much pain.

Thoughts very welcome.

Couple of questions on the MR.

Thanks, that clarified a bit.

For the revisioning UI, what if the edit forms have radio buttons, with no default selection, instead of a revision checkbox? So editors have to make a conscious choice of which option they want. They could be labelled with some detail, like:

○ Update current version. Apply these changes immediately for all current students. Recommended for minor edits, such as typo corrections, that don't affect the overall meaning or scoring.

○ Create new revision. This version will only be shown to new students; existing students will remain on the previous revision. Recommended for any major changes.

For the revisioning UI, what if the edit forms have radio buttons, with no default selection, instead of a revision checkbox?

It's one extra click in the UI vs a conscious choice. I have no idea really, we need to get more opinions on this, preferably something for later as it's something very easy to alter by project anyway.

We would need to only change the form when the revision mode is enabled, so content editors would get a different form depending on configuration, which could be somewhat confusing?

I have a question (and I think we should add some documentation about it) for what this means for lessons that aren't taken yet.

Currently course_status entities don't reference lessons, so it seems like changes to which lessons are in a course won't respect the revision setting?

Assume I have a course A with lessons 1 and 2.

All of these things could happen:

Lesson 1 is removed.

Lesson 2 is removed.

Lesson 3 is added.

A new activity is added to lesson 2

An activity in lesson 2 is edited.

What I think should happen is that activity changes in not-yet-started lessons should not be affected by the revision setting, this is because there would not yet be a lesson_status entity yet. If there's not yet a lesson_status entity, then we can use the default revision of the lesson up until the user starts to take it, and only from that point would changes take place. As far as I can tell that's how things would work with the current MR, and it's also what I think the correct behaviour is.

Because the lesson_status activity includes a reference to every activity, I'm assuming that as soon as a lesson is started, any changes to activities, including not-yet-taken ones, would not have an effect in revision-mode because they all change to revision references.

However, if we don't have a lessons reference on course_status, then it feels like there wouldn't be equivalent behaviour there, and I'm not entirely sure what the behaviour should be - e.g. should revision mode allow you to add lessons to the end of a course? Or not?

@catch lessons of a started course respect same rules when revisions are enabled, it's just the entity loading logic is different:
course_status -> lesson status (if exists) -> lesson revision reference

Merged but this will be released in a new minor beta so it gets sufficient testing and feedback from the community before being marked as stable.

Automatically closed - issue fixed for 2 weeks with no activity.