/
Content Libraries Sync Notes

Content Libraries Sync Notes

@Kyle McCormick @Dave Ormsbee (Axim) @Braden MacDonald @Jenna Makowski @Marco Morales @Sam Daitzman @Maksim Sokolskiy @Scott Dunn

 

Evergreen topics:

 

Dec 5, 2025

  • @Sam Daitzman: following up, I think there was a small patch planned to add some limited links from course content to the library content it references-- is that still planned?

    • → Not yet, Dave looked into it

  • @Kyle McCormick - Legacy migration, status & concerns

    • PR we need to land some version of before the release:https://github.com/openedx/edx-platform/pull/37711

      • user-facing issues it is fixing:

        • [not release blocking] editability of legacy libraries post-migration

        • [not release blocking] spurious sync after converting a reference

      • REST API facing issues it is fixing:

        • [not release blocking] inconsistent decision making around what entities and collections to update when the “update”/”skip” strategies are specified. This is not important for the UI because it always uses “fork”, but Scott’s use case sounded like he’d be using “update”/”skip”

      • General improvements to code consistency and comprehensibility. Which normally I’d try to land NOT in Ulmo, but we’re seeing other migration issues, and I’m wondwering if they’re related

    • Decision: these are not release blockers, they do not affect the vast-majority use cases. Will try to get some fixes into ulmo.1, but can become part of ulmo.2 otherwise

Nov 28, 2025

Nov 21, 2025

  • @Sam Daitzman: User-facing sync / publish behavior documentation

    • Requested at Educators WG

    • Requested here as well: https://github.com/openedx/docs.openedx.org/issues/1298

    • Sarina: want to move toward how-to articles in documentation, testing should just be “follow this how-to and report unexpected behavior”

    • Action item: ideally before the Ulmo release (Dec 9): send @Sarina Canelake high-level overview of publish / sync happy path

  • @Kyle McCormick legacy libraries migration release notes / docs

    • …

  • Meeting Visibility / Cross-Org Input and Recaps

    • @Marco Morales - flagging based on prior conversations about cross-org initiatives

  • @Edward Byun / @Sam Daitzman: https://github.com/openedx/frontend-app-authoring/issues/2626#issuecomment-3555417120

    • Steps:

      • 1. Migrate legacy library

        • 1.5. Publish all migrated

      • 2. Update reference

      • 3. Update content from updates pane

    • If step 1.5 exists: someone rewrites the content, then skipping step 3 or auto applying it will have unexpected results

    • @Kyle McCormick: may be possible to detect this case (step 3 being spurious). If the legacy course content was up-to-date, and there has been no non-migration-triggered version update in new libraries, may be able to ignore the update / not present it

      • Kyle figured this out and will make a PR for it.

Oct 31, 2025

  • @Sam Daitzman: checking in on settings status

  • @Sam Daitzman: release testing / RBAC overlap

    • plan to delay testing until RBAC lands?

    • are we concerned about overlap?

    • Braden:

      • let’s consider that to be BTR’s testing plan

      • we can still test in a more fine-grained way on our own and just ignore RBAC

  • Have we tested on Indigo theme / depending on BTR group and Tutor outcome of BTR thread (if BTR decides to test with Indigo theme applied), we may want to check on libraries support

  • It looks like nobody is using python_lib.zip in practice.

  • Test process

    • Dave: Are we adding our cases to the giant spreadsheet?

    • Sam:

  • UX Discussion: When published components are added to a unit, or components are individually published within a unit, it’s not obvious that the unit itself is still in draft and the published version doesn’t yet show those new components.

    • Proposed short-term fixes:

      1. add a “draft” / “unpublished changes” label to the unit header / unit info button
        -> we decided this is the best short-term fix for Ulmo

      2. add content type icon to sidebar to make it more obvious what thing you’re publishing

      3. after publishing child object, switch to parent object info sidebar

    • Proposed long-term fixes

      1. Add a “What the student will see.” / “Published” tab that shows the published view in the library

      2. Hide component-level publish buttons entirely when you’re on a unit page

        1. But then should they also be hidden when you access a component separately but it’s only used in one parent unit? → Gets to Scott’s question about intended level of re-use and how we don’t acknowledge that anywhere in the UI.

      3. add persistent page-level draft status / publish action (basically requires layout restructure I would not recommend after feature cut)

Oct 24, 2025

Oct 17, 2025

  • Sam: When we were testing the migration, there was one time when they encountered a failed migration state (@Edward Byun ran into this). It seemed like some libraries were migrated in, but none were assigned to collections. Question: Is the migration codebase set up so that operations are atomic (either all works or all fails).

  • Marco: We’re making progress on post-Ulmo stuff. If there’s anything that the team would benefit from sizing activities, etc. where we’re blocked on UX questions, please contact them. But currently closing out Ulmo is highest priority. Want to make sure there are no other blockers.

  • Sam: Is it possible to create some test libraries that will cause migration errors?

    @Kyle McCormick will create these test libraries to cause errors for testing.

  • Braden will take a look at https://github.com/openedx/frontend-app-authoring/pull/2532 , but in general it’s okay for Diana or others who are CCs with access to that repo merge. Braden is the default reviewer and gets notifications on everything.

  • Restore screen discussion

    • Sam provided updated adjustments to the Figma screen for the restore screen, to include where the archive came from.

    • We’ll continue to have extra metadata in the archive about things like “number of units”, “number of subsections”, etc. Even if we’re not doing it for now because it would crowd the UX, we may want to display them later.

    • We will not implement a “change the archive” flow. If you uploaded the wrong archive, you can go back and create new again.

    • Javier is out next week, but he will transition work to someone else on his team.

  • Opaque Keys discussion postponed to post-Ulmo-cut

 

Oct 10, 2025

  • Testing migration process:

    • Obtain some text export V1 libraries (from Colin?), import into sandbox, then test the migration process

    • How many? as many as possible

  • UX/UI presentation: Thinking about course outline sidebar and FE slot

  • @Jenna Makowski / @Sam Daitzman : sidebar pattern epic planning and spec

    • Likely ~3 epics across: sidebar plugin slots on course outline/unit view, outline/unit sidebars and selection pattern (could be split), library bulk actions

    • What questions should initial spec to unblock the plugin slot work answer?

    • What would be helpful to unlock the first round of development work on this?

    • Some thoughts in: https://github.com/openedx/frontend-app-authoring/issues/1958

    • Questions to answer

      • Are sidebars resizable? Responsive approach?

      • Sequencing: how do we avoid overwhelming authors? What is the first increment of change?

      • Are we eventually going to support bulk actions, either through multi-selection or another interface?

        • Would be helpful to plan for this even if not shipping it quickly

      • If you close a sidebar, can you reopen it or do you have to press the same button to open it again?

      • How do sidebar states interact with URLs, can you share a URL with a specific sidebar open in a specific state?

      • Plugin architecture: what slots do we want to support?

        • Extensibility: at a site level, course level, etc.?

      • Design / product principles for sidebars vs. modals vs. inline: how do we generally want to prioritize?

        • Frequency of use / frequency of repeat tasks

        • Benefit of in-context / multi-modal actions vs. irrelevant for some actions

      •  

Oct 3, 2025

  • Code cut pushed out 2 weeks

  • Check in re Course library related Advanced settings (educator visibility, use, etc)

  • Testing plan for V1 ---> V2 migration workflows

  • Seeking input on UI for “migrating” a randomized Legacy Library reference into a Problem Bank after its source library has already been migrated.

    • WIP UI:

      • image-20251002-193331.png

    • Text under the migratable legacy reference:

      • e.g. “The source has been migrated to a new library. <Check for updates>”

      • or just use the standard update text

        • Sam approves

        • Eddie is going to think on it

        • should this apply the update from the v2 library, or just check for it?

          • dave approves of applying the update at the same time

            • and if sync from v2 fails, then leave it as a legacy reference

      • course-level admin action for updating all legacy references

    • Also noted: exporting a course with migrated references into an older instance should still allow the v1 library sync flow (i.e. we keep the old field value there)

    • Decisions recorded here: https://github.com/openedx/frontend-app-authoring/issues/2386#issuecomment-3372472237

Sep 26, 2025

  • Any blockers, particularly on the migration epics?

  • Any concerns about Ulmo timeline?

  • @Edward Byun https://github.com/openedx/edx-platform/issues/37327 Wanted to confirm: 50 legacy libraries per migration?

    • We suggest 50 libraries per page limit, pagination, and limiting migration to page-in-view

    • Updated designs / detailed spec coming soon on frontend migration ticket

  • Finding a time for Pearson API import workshop

  •  

Sep 19, 2025

  • @Sam Daitzman: demo of section-/subsection- level library authoring and course reuse experience

  • @Edward Byun Deletion for Ulmo. There are some conversations to have in the future, but want to keep this to Ulmo focused.

    • Child components: parent shows as requiring a sync after parent is published (treated as a content edit; publish cascade implementation for deletions/removals for Ulmo will differ slightly)

      • Deletion = publishable action with no viewable entity (publish all publishes the object, and publishing parent can cause sync because of null reference / updated list of references)

    • Stand-alone and deleted at level of reuse: broken link icon appears immediately in course instance of deleted library object

      • For containers, this means if there are published changes to descendants, course will not be able to see unless user sees broken link icon and unlinks the container.

      • Three options from least effort to most:

        • Do nothing. Downside: relies on users seeing broken link icon to get visibility, and relies on users knowing to unlink (if they want to get updates).

        • Auto un-link. Downside: loses level of intended reuse with low visibility to users. May cause future issues for permissions / publish model.

          • Auto un-link raises some questions: when does this unlink happen? How can we differentiate (to user) permission loss vs. an object being deleted? What happens when the object is restored from trash?

        • Add broken links section to Library Updates page as a new category. Downside: Dev effort: need new CTA interface and action modals to communicate child object deletion (or could just surface as a top-of-page health indicator / count).

      • For Ulmo, we recommend doing nothing. There are some real questions about intent that should be addressed through interviews/ discovery, ‘do nothing’ for now allows us to move forward in some direction in the future without having to backtrack on some decision here.

  • @Edward Byun GitHub issue tracking remaining Ulmo tasks: https://github.com/openedx/frontend-app-authoring/issues/2462 . I’ll update as we go through and address tickets.

  • @Dave Ormsbee (Axim) Resiliency questions on error handling in restore.

    • Decision: Fail the whole creation for Ulmo. Will need to do something more resilient for partial import of large libraries post-Ulmo. We’ll generate an error log file as a downloadable artifact. Target audience is technical, so debug info here.

Sep 12, 2025

  • @Sam Daitzman: Share out Verawood design priorities / discuss scoping and areas that could use definition soonest to support future Verawood development.

    • https://docs.google.com/document/d/1rW8N0ZZvro_R2qOD_3vdhMsCjQLgl5cU7NVs2NSG4Fc/edit?tab=t.0#heading=h.oist3sff46w1

    • Overrides

      • Text overrides, as previously planned

      • Possibly partial sync by un-linking. For example, Section is linked, but you only want to sync a subset of its Subsections. So, you “unlink” the Section, and now you can sync individual Subsections.

      • Not targeting more complicated overrides.

    • Inheritance

      • Q: In a course, can you set max_attempts at the Section level and have it inherit down?

        • Yes, in OLX. Not in the UI.

      • But, for library-referenced content, each individual Problem sets a max_attempts, so the Section-level-OLX-set inherited value would be ignored.

    • Templates?

      • Not for verawood probably

      • Rather, we’re taking advantage of all the structural block work that has happened

    • Dynamic content in libs - not targeting for Verawood

    • Dave: would be cool to do cross-library search.

      • Braden: this is basically ready to go, can turn it on when it’s wanted

  • @Kyle McCormick Legacy Course Unit and Problem editors will still be available in Ulmo. IMO, we don’t need to support library syncing in these legacy editors, but we should have some graceful degradation or error mesage. i.e., the legacy editors shouldn’t raise a 500 or corrupt the course if you’re looking at lib-linked content.

    • In what cases will someone see legacy editor? (Is it: manually toggled that on?)

      • Course-level or instance-level toggle; only reason to have it toggled on is for advanced use cases new problem editor won’t yet support, or new problem editor bugs are an issue for you

    • In what cases would they need the legacy editor?

    • Legacy problem editor should be fine with library-linked problems

    • Legacy unit editor, we’ll need to test

    • @Kyle McCormick will follow up on this

Sep 5, 2025

  • Discussed import / migration epics

    • May need to add a limit to the number of legacy libraries that can be migrated at once. Holding off for now.

    • Updated epic/story structure to clarify bounds between backend import, migration backend, migration frontend, and [future/pending] frontend import course library

@Sam Daitzman Text override messaging

  • Designs ready to discuss

@Sam Daitzman Publish cascade discussion [continued from last time]

  • Intended vs. current deletion cascade behavior

    • Child object deletion or removal should add draft status within library, and be a publishable and syncable edit to the parent

    • E.g. A subsection contains two draft units. Publishing both units also implicitly publishes the subsection, but no one has reviewed the subsection as a whole.

 

Aug 29, 2025

  • From @Kyle McCormick via Slack:

    • Max can give an update on the Course-to-Library Import API.

    • I think I've given OpenCraft the info they need to be unblocked for now on the Legacy Library migration frontend, but if anything is missing please let me know.

    • I still need to finish grooming the story(ies) for the rest of the Legacy Library migration backend work, this is high in my priority queue.

    • I'm making progress on dynamic content modelling . The data model intersects with the data model that the UserGroups project is working on, so I've been paging that in lately.

  • @Sam Daitzman / @Edward Byun Product conversations:

    • Text overrides and sync

      • details in August 22 note below.

      • Decision:

        • show sync dialog, modify messaging to explain local overrides will be kept

        • always keep local overrides

        • create simple document explaining sync behavior for Ulmo

    • Tagging and Publishing

      • Tags assigned on library side appear on course side without publish. Is there any permissions issue here? (e.g. if library view permission is lost)

      • Course tags editable locally, but library tags are not (sync in automatically, cannot be edited)

      • Tag changes not treated as content edits / unrelated to draft status in library / do not appear in history

        • On sync, latest tags are brought over (not latest published tags)

      • Tags are not tracked in any log

    • Publish/sync cascade behavior

      • Publish expected behavior: cascades down (e.g. publishing a section publishes all subsections within it, and so on)

      • Sync behavior clarification: should a sync be available when publish occurs at the level of reference (e.g. publishing a unit does not makes a referenced section containing it show a new sync) or whenever any library sub-object has a new version available (e.g. publishing a unit makes a referenced section containing it show a new sync, even if it has no other changes)

        • Does publish mean:

          • Draft status is removed in library, object appears as published

          • Object is available for sync on course side (regardless of reference level)

        • Example: S1 contains SS1, SS2. When SS1 is published with some changes, should sync be available for S1 if it was not explicitly published?

          • Do we differentiate a case where SS1’s published edit is the only change since last publish vs. where SS2 also has independent draft or published edits?

        • First case downside: publishing a unit may not offer updates to all instances, and child-of-reference/top-level-reference course instances may therefore differ after accepting all available syncs

        • Second case issues: (1) clashes slightly with communicated behavior in publishing behavior visualization diagram, and (2) it circumvents multistep publishing level checks, i.e. a section will be synced to a version that was never explicitly reviewed as a complete object with a summary of changes

    • Copy/paste behavior re: references

      • Currently copy-paste seems to include references

      • Copying a draft and pasting it includes a reference, leading to some undefined/undesirable potential behavior

      • We should clarify this behavior / define expected behavior

        • Option A: copying a draft shows a dialog that forces publish before copying, or cancel

        • Option B: copy-paste is content only, no

Aug 22, 2025

  • @Edward Byun Text overrides and sync:

    • Wanted to discuss decisions around not showing available syncs to users for library text blocks that are edited locally

Context: We’re allowing text overrides for Ulmo, but we also have the following temporary limitations for Ulmo:

  • The sync modal may not show a diff of component before/after state for reused content blocks.

  • We will not support partial syncs (ie syncing parts of a published update but keeping some other local overrides).

Pending decision:

Given the above, we think locally overridden library text blocks should not receive updates when a new version is published at the library. Without giving users the visibility and tools, we want to avoid the possibility of accepting a sync without understanding the implications, and blowing away local edits.

Cases to discuss:

  1. A library text block is added into a course created unit. An educator edits that component. When a new version of that block is published from a library we think the block should not appear on the library updates page, and should not have an available sync icon.

  2. A library text block is reused into a course as part of a library unit. An educator edits the text block. A new version of the unit is published where the only change is to the text block ie: no reorders, no other changes to any other content of that library sourced unit. In this case, we think the unit should also not appear on the library updates page, and should not have an available sync icon.

  3. As above, a library text block is reused as part of a Library Unit to a course, and an educator makes a local text override). A new version is published from the library where multiple edits are made including a change to the locally edited text block. What should happen in this situation?

  • Tagging and Publishing