Cbe assessment criteria versioning adr by mgwozdz-unicon · Pull Request #476 · openedx/openedx-core

mgwozdz-unicon · 2026-02-04T20:22:51Z

No description provided.

openedx-webhooks · 2026-02-04T20:22:56Z

Thanks for the pull request, @mgwozdz-unicon!

This repository is currently maintained by @axim-engineering.

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.

Details

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:

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.

bradenmacdonald · 2026-02-05T00:05:13Z

If we're not going fully versioned (via PublishableEntity) for now, I would recommend at the least that you add the HistoricalRecords() model from django-simple-history, which is a well-established pattern used by many other parts of the LMS/CMS to preserve historical data. It's basically just one line of code and then you get a complete auditable record of all changes to the data, so I don't think there's much downside.

mgwozdz-unicon · 2026-02-10T19:28:18Z

If we're not going fully versioned (via PublishableEntity) for now, I would recommend at the least that you add the HistoricalRecords() model from django-simple-history, which is a well-established pattern used by many other parts of the LMS/CMS to preserve historical data. It's basically just one line of code and then you get a complete auditable record of all changes to the data, so I don't think there's much downside.

This is a great idea. I updated the ADR accordingly.

ormsbee · 2026-03-19T04:26:04Z

docs/decisions/0023-competency-criteria-versioning.rst

+
+Typically, only one person would be responsible for entering competency achievement criteria rules in Studio for each course, though this person may change over time. However, entire programs could have many different Course Authors or Platform Administrators with this responsibility. 
+
+Typically, institutions and instructional designers do not change the mastery requirements (competency achievement criteria) for their competencies frequently over time. However, the ability to do historical audit logging of changes within Studio can be a valuable feature to those who have mistakenly made changes and want to revert or those who want to experiment with new approaches.


FWIW, one of the issues that comes up around grading from time to time is the principle that someone should keep the grade that they saw themselves get, regardless of what changes the course team makes, unless that change was necessary to correct a bug (and often not even then). So the equivalent in competencies might be to make sure that by default we don't remove someone's competency because an author made some changes to how those competencies are earned.

Is it safe to assume that just preserving the timestamp they earned the competency would be sufficient to later reconstruct the state of the how the assessment criteria/grouping was defined at that point?

I realized that my Decision description wasn't very specific or detailed, so I updated it to explicitly state which tables would have django-simple-history applied to them to enable reconstruction of the state of how learner statuses were determined previously if needed.

ormsbee

Looks great! Just had a few very minor comments and requests.

ormsbee · 2026-03-28T21:07:42Z

docs/decisions/0023-competency-criteria-versioning.rst

+
+Typically, institutions and instructional designers do not change the mastery requirements (competency achievement criteria) for their competencies frequently over time. However, the ability to do historical audit logging of changes within Studio can be a valuable feature to those who have mistakenly made changes and want to revert or those who want to experiment with new approaches.
+
+Currently, Open edX always displays the latest edited version of content in the Studio UI and always shows the latest published version of content in the LMS UI, despite having more robust version tracking on the backend (Publishable Entities). Publishable Entities for Libraries is currently inefficient for large nested structures because all children are copied any time an update is made to a parent.


Suggested change

Currently, Open edX always displays the latest edited version of content in the Studio UI and always shows the latest published version of content in the LMS UI, despite having more robust version tracking on the backend (Publishable Entities). Publishable Entities for Libraries is currently inefficient for large nested structures because all children are copied any time an update is made to a parent.

Currently, Open edX always displays the latest edited version of content in the Studio UI and always shows the latest published version of content in the LMS UI, despite having more robust version tracking on the backend (Publishable Entities).

We do represent container structures more efficiently now, so that each subtree can change without forcing a new version of the parent to be made. I don't think this is an important point to make here, but I just think we should remove this line as it's no longer accurate.

ormsbee · 2026-03-28T21:10:55Z

docs/decisions/0023-competency-criteria-versioning.rst

+   - `oel_competency_criteria_group`
+   - `oel_competency_criteria`
+   - `oel_competency_rule_profile`


As with the last PR, it's probably easier to just list the models, rather than worrying about Django conventions for translating that to tables.

ormsbee · 2026-03-28T21:12:25Z

docs/decisions/0023-competency-criteria-versioning.rst

+1. Defer competency achievement criteria versioning for the initial implementation. Store only the latest authored criteria and expose the latest published state in the LMS, consistent with current Studio/LMS behavior. 
+    - Pros: 
+        - Keeps the initial implementation lightweight
+        - Avoids the publishable framework's known inefficiencies for large nested structures


Suggested change

- Avoids the publishable framework's known inefficiencies for large nested structures

ormsbee · 2026-03-28T21:13:11Z

docs/decisions/0023-competency-criteria-versioning.rst

+    - Cons:  
+        - Requires custom conventions for versioning across related tables and nested groups  
+        - Lacks shared draft/publish APIs and immutable version objects that other authoring apps can reuse  
+        - Not necessarily consistent with existing patterns in the codebase (though these are already not overly consistent).   


(though these are already not overly consistent)

😆

ormsbee · 2026-03-28T21:14:00Z

docs/decisions/0023-competency-criteria-versioning.rst

+        - First-class draft/published semantics with immutable historical versions  
+        - Consistent APIs and patterns shared across other authoring apps  
+    - Cons:  
+        - Inefficient for large nested structures because all children are copied for each new parent version  


Suggested change

- Inefficient for large nested structures because all children are copied for each new parent version

mgwozdz-unicon added 5 commits February 4, 2026 13:08

docs: add ADR 0020 assessment criteria location

743034b

docs: Increment ADR number

cc0ec47

docs: add ADR 0021 assessment criteria versioning

b844049

docs: Increment ADR number

236ef76

docs: remove location adr from versioning adr branch

1100d8a

openedx-webhooks added the open-source-contribution PR author is not from Axim or 2U label Feb 4, 2026

openedx-webhooks added this to Contributions Feb 4, 2026

github-project-automation bot moved this to Needs Triage in Contributions Feb 4, 2026

mgwozdz-unicon requested a review from ormsbee February 4, 2026 20:23

mgwozdz-unicon mentioned this pull request Feb 4, 2026

CBE Assessment Criteria ADRs #466

Closed

mphilbrick211 moved this from Needs Triage to Ready for Review in Contributions Feb 9, 2026

docs: Use django-simple-history for versioning

91697af

ormsbee reviewed Mar 19, 2026

View reviewed changes

docs: clarify specific history tracking and traceability

069d22e

mgwozdz-unicon requested a review from ormsbee March 24, 2026 20:12

ormsbee requested changes Mar 28, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Cbe assessment criteria versioning adr#476

Cbe assessment criteria versioning adr#476
mgwozdz-unicon wants to merge 7 commits intoopenedx:mainfrom
mgwozdz-unicon:cbe_assessment_criteria_versioning_adr

mgwozdz-unicon commented Feb 4, 2026

Uh oh!

openedx-webhooks commented Feb 4, 2026 •

edited

Loading

Uh oh!

bradenmacdonald commented Feb 5, 2026

Uh oh!

mgwozdz-unicon commented Feb 10, 2026

Uh oh!

ormsbee Mar 19, 2026

Uh oh!

mgwozdz-unicon Mar 24, 2026

Uh oh!

ormsbee left a comment •

edited

Loading

Uh oh!

ormsbee Mar 28, 2026

Uh oh!

ormsbee Mar 28, 2026

Uh oh!

ormsbee Mar 28, 2026

Uh oh!

ormsbee Mar 28, 2026

Uh oh!

ormsbee Mar 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants


		Typically, only one person would be responsible for entering competency achievement criteria rules in Studio for each course, though this person may change over time. However, entire programs could have many different Course Authors or Platform Administrators with this responsibility.

		Typically, institutions and instructional designers do not change the mastery requirements (competency achievement criteria) for their competencies frequently over time. However, the ability to do historical audit logging of changes within Studio can be a valuable feature to those who have mistakenly made changes and want to revert or those who want to experiment with new approaches.


		Typically, institutions and instructional designers do not change the mastery requirements (competency achievement criteria) for their competencies frequently over time. However, the ability to do historical audit logging of changes within Studio can be a valuable feature to those who have mistakenly made changes and want to revert or those who want to experiment with new approaches.

		Currently, Open edX always displays the latest edited version of content in the Studio UI and always shows the latest published version of content in the LMS UI, despite having more robust version tracking on the backend (Publishable Entities). Publishable Entities for Libraries is currently inefficient for large nested structures because all children are copied any time an update is made to a parent.

Conversation

mgwozdz-unicon commented Feb 4, 2026

Uh oh!

openedx-webhooks commented Feb 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bradenmacdonald commented Feb 5, 2026

Uh oh!

mgwozdz-unicon commented Feb 10, 2026

Uh oh!

ormsbee Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

mgwozdz-unicon Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

ormsbee left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ormsbee Mar 28, 2026

Choose a reason for hiding this comment

Uh oh!

ormsbee Mar 28, 2026

Choose a reason for hiding this comment

Uh oh!

ormsbee Mar 28, 2026

Choose a reason for hiding this comment

Uh oh!

ormsbee Mar 28, 2026

Choose a reason for hiding this comment

Uh oh!

ormsbee Mar 28, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

openedx-webhooks commented Feb 4, 2026 •

edited

Loading

ormsbee left a comment •

edited

Loading