feat: New `history log` api functions [FC-0123] by ChrisChV · Pull Request #501 · openedx/openedx-core

ChrisChV · 2026-03-16T23:12:09Z

Description

Implements python api functions to get and build the history log of an entity:
- get_entity_draft_history: Return DraftChangeLogRecords for a PublishableEntity since its last publication.
- get_entity_version_contributors: returns the users who authored changes between two published versions of an entity
- get_entity_publish_history: Return all PublishLogRecords for a PublishableEntity
- get_entity_publish_history_entries: Return the DraftChangeLogRecords associated with a specific PublishLog
- get_descendant_component_entity_ids: BFS traversal of a container hierarchy, returning the IDs of all descendant component entities (used to scope queries when fetching history for
  container children)
Which edX user roles will this change impact? "Developer".

Supporting information

Testing instructions

Follow the testing instructions in openedx/frontend-app-authoring#2948

Deadline

Before the Verawood cut.

Other information

N/A

openedx-webhooks · 2026-03-16T23:12:15Z

Thanks for the pull request, @ChrisChV!

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.

ormsbee · 2026-03-18T16:16:28Z

+    Return DraftChangeLogRecords for a PublishableEntity since its last publication,
+    ordered from most recent to oldest.
+
+    If the entity has never been published, all DraftChangeLogRecords are returned.


What is the intended behavior of this function when the last "publish" was a deletion?

I think the current code does work in this case, to be clear. And I realize that it's not something that's likely to come up in the UX. I just want to make sure that the behavior is well defined and tested for in that edge case.

Thanks! Yes, I'll add tests for that case.

ormsbee · 2026-03-21T22:03:01Z

High level comment: please note that it's possible to reset a draft to the published state (i.e. discard changes). When that happens, the Draft version is reset to point to the same version as Published, but all the versions created still exist and are reflected in the draft change log.

… changes

rpenido

Looking good @ChrisChV!

rpenido · 2026-03-27T20:49:39Z

+        .values_list("draft_change_log__changed_by", flat=True)
+        .distinct()
+    )
+    return get_user_model().objects.filter(pk__in=contributor_ids)


Do you think it is worth adding an order_by here to assert consistent results?

ormsbee · 2026-03-28T19:10:45Z

Per this slack thread, I think we're going to want to extend the PublishLog model to include a nullable field that captures what it was that the user clicked "publish" on. Right now, if there is a Subsection -> Unit -> Component setup where only the component has changed, the data in the PublishLog does not allow us to differentiate which level the user pressed "Publish" at, and this seems to be a requirement of the UX.

Does this sound correct to you @sdaitzman, @marcotuts?

FYI @crathbun428, @jmakowski1123

ormsbee · 2026-04-06T15:32:02Z

I made a separate issue to capture user publish intent (my comment above), so that we can discuss in more detail: http://github.com/openedx/openedx-core/issues/533

ormsbee · 2026-04-13T16:55:35Z

+    # If reset_drafts_to_published() was called within this publish window, there
+    # will be a DraftChangeLogRecord where new_version == baseline. Use the most
+    # recent such record as the new lower bound so discarded entries are excluded.


I know I was the one who flagged this because I wanted to make sure the code noted it, but I actually don't think we should filter out discarded changes. It's a log, and "discard changes" is a legit thing that someone in that chain of edits did. I think we should be explicit that it happened, especially if people are going here because they're thinking, "I know I was working on this, but what happened to my edits!?!" Then they could see "Dave discarded changes" and know who to ~~strangle~~ talk to.

ormsbee · 2026-04-13T17:03:15Z

+
+def get_descendant_component_entity_ids(container: Container) -> list[int]:
+    """
+    Return the entity IDs of all leaf (non-Container) descendants of ``container``.


Code in the containers applet shouldn't be querying Draft models directly, or ideally even be aware of components.

Where is this going to get called from?

Code in the containers applet shouldn't be querying Draft models directly, or ideally even be aware of components.

I've refactored the function to not use Draft

Where is this going to get called from?

This function is called in edx-platform, in get_library_container_draft_history and in get_library_container_publish_history. This is what I have implemented, as I mentioned in Slack. It might change later after implement the direct field.

…Draft`

ormsbee

Partial review. Will add more in the morning. Thank you.

ormsbee · 2026-04-21T20:28:33Z

+    reset_filter = {
+        "entity_id": entity_id,
+        "new_version_id": baseline_version_id,
+        "draft_change_log__changed_at__lte": published_at,
+    }
+    if prev_published_at:
+        reset_filter["draft_change_log__changed_at__gt"] = prev_published_at
+
+    last_reset_at = (
+        DraftChangeLogRecord.objects
+        .filter(**reset_filter)
+        .order_by("-draft_change_log__changed_at")
+        .values_list("draft_change_log__changed_at", flat=True)
+        .first()
+    )


Per @sdaitzman, we should represent the Discard Changes action as another kind of draft update, so we don't need to filter them out here.

ormsbee · 2026-04-22T04:13:53Z

+    Intermediate containers (e.g. Subsections, Units) are never included in the
+    result; only leaf component entities are returned.


[Question] Why do we only focus on Components and exclude intermediate containers? Don't we need to include changes to intermediate Containers to build a historical view of the parent Container?

This implementation follows the logic discussed in openedx/frontend-app-authoring#2805 (comment)

For Containers, both lists follow the same structure and contain:

All direct edits made to the container itself.

All edits included in each publish group, for all descendant components.

E.g. for a section, an edit to a component grouped under a prior publish shows one edit, to that component (not to any in-between levels, or to the direct child subsection that is an ancestor of the component)

So does a rename of a Unit never show up at all?

It is shown in the unit's history log:

All direct edits made to the container itself.

The logic I understood here is to show the important changes, which are the components, in the log. If we show only intermediate changes, for example, in a section's history log, it can display so many changes that it might overwhelm the user.

The current implementation keeps it compact and with relevant information.

I guess I would expect it to show non-side-effect changes, i.e. ones where the actual version_num of the record changes. Because otherwise, we'd miss things like "Deleted this Unit", or "Removed this Subsectino" which are really big changes.

ormsbee · 2026-04-22T04:25:22Z

    )
+
+
+def get_descendant_component_entity_ids(container: Container) -> list[int]:


I know you're framing this as descendants using container traversal, but publishing follows the (very closely related) concept of dependencies. Unless you absolutely need to frame this in terms of containers, it might make more sense to do dependency traversal similar to how we traverse dependencies for publishing. It will likely be faster as well.

One of the reasons I mention this is that we will eventually have dependencies that live outside of the container->child relationship, like media assets, and eventually course-related things like grading policies.

ormsbee

Please mark the new API calls as "[ 🛑 UNSTABLE ]" in their docstrings, like the containers APIs are.

Otherwise, two very small change requests to keep component knowledge out of the publishing applet. I realize that we may have to revise this pending further UX refinement, but this is really excellent work—very clearly written and well commented. Great job!

ormsbee · 2026-04-23T02:12:02Z

+        .filter(entity_id=entity_id)
+        .select_related(
+            "draft_change_log__changed_by",
+            "entity__component__component_type",


Please get rid of this line here, and add it on as a .select_related() when this gets called from get_library_component_draft_history(), like:

history_qs = content_api.get_entity_draft_history(component.publishable_entity) records = list(history_qs.select_related("entity__component__component_type")

Since get_library_component_draft_history() is aware of components anyway and is actively traversing them, I think it's better to keep that knowledge out of the publishing applet as much as possible.

ormsbee · 2026-04-23T02:13:11Z

+        .filter(entity_id=entity_id)
+        .select_related(
+            "publish_log__published_by",
+            "entity__component__component_type",


Likewise, please remove this line and add it back in as a select_related call from get_library_component_publish_history()

feat: get_entity_draft_history added

6f4b1dc

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

openedx-webhooks added this to Contributions Mar 16, 2026

ChrisChV marked this pull request as draft March 16, 2026 23:12

github-project-automation Bot moved this to Needs Triage in Contributions Mar 16, 2026

ChrisChV changed the title ~~feat: New history log api functions~~ feat: New history log api functions [FC-0123] Mar 16, 2026

ormsbee reviewed Mar 18, 2026

View reviewed changes

feat: contributors, publish groups and publish entries functions added

c492314

mphilbrick211 added the FC Relates to an Axim Funded Contribution project label Mar 23, 2026

mphilbrick211 moved this from Needs Triage to Waiting on Author in Contributions Mar 23, 2026

fix: return draft and published entries of a component with discarted…

3823f5a

… changes

This was referenced Mar 24, 2026

feat: History log in content library components and containers [FC-0123] openedx/frontend-app-authoring#2948

Open

feat: History log logic for Components and Containers [FC-0123] openedx/openedx-platform#38178

Open

ChrisChV added 2 commits March 24, 2026 18:21

feat: Pre-fetch the component type in the queries

8e270a7

feat: get_descendant_component_entity_ids function added

723fe11

rpenido reviewed Mar 27, 2026

View reviewed changes

Merge branch 'main' into chris/FAL-4330-history-log

1fefef3

ormsbee reviewed Apr 13, 2026

View reviewed changes

ChrisChV added 5 commits April 13, 2026 13:23

refactor: Update get_descendant_component_entity_ids to avoid use `…

4ac8d44

…Draft`

Merge branch 'main' into chris/FAL-4330-history-log

bafab85

fix: Broken lints

6b423f2

Merge branch 'main' into chris/FAL-4330-history-log

6ac9384

fix: Broken tests

ddf5ff7

ChrisChV mentioned this pull request Apr 21, 2026

feat!: Collection.key -> Collection.collection_code #542

Merged

ChrisChV marked this pull request as ready for review April 21, 2026 02:16

ChrisChV requested a review from ormsbee April 21, 2026 02:16

ormsbee requested changes Apr 22, 2026

View reviewed changes

ormsbee requested changes Apr 23, 2026

View reviewed changes

		Intermediate containers (e.g. Subsections, Units) are never included in the
		result; only leaf component entities are returned.

		)


		def get_descendant_component_entity_ids(container: Container) -> list[int]:

Conversation

ChrisChV commented Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Supporting information

Testing instructions

Deadline

Other information

Uh oh!

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

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ormsbee commented Mar 21, 2026

Uh oh!

rpenido left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ormsbee commented Mar 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ormsbee commented Apr 6, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ormsbee left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

ChrisChV commented Mar 16, 2026 •

edited

Loading

openedx-webhooks commented Mar 16, 2026 •

edited

Loading

ormsbee commented Mar 28, 2026 •

edited

Loading

ormsbee left a comment •

edited

Loading