Merge openedx/xblock-utils library into openedx/XBlock

[kdmccormick]

Background

Pros of having this as a separate package

• Code separation: XBlock's core cannot depend on these utilities
  • However: importlinter could be used instead.
• XBlock doesn't depend on Django
  • However: I can't find the ADR, but somewhere we decided that Django should be assumed for XBlocks, since enforcing Django-agnosticness wasn't yielding any value.

Cons of having this as a separate package

• More maintenance overhead. We can't assume XBlock authors use xblock-utils, so we must maintain XBlock as a proper interface on its own. For example, moving off pkg_resources would be simpler if every block just used the ResourcesLoader interface that xblock-utils provides.
• Harder to document: Two sets of documentation & common patterns need to be maintained -- docs for using XBlock without xblockutils, and docs for xblockutils itself.
• More choices for XBlock developers. "Should I use xblockutils or not??"
• More setup steps for XBlock developers.
• Indirection: the system is harder for developers to understand when there's extra layers.
• Maintenance difficulty:

Acceptance Criteria

Tasks

Beta Give feedback

1. understand why the two libraries were separate in the first place (done: see Braden's comment below)
2. make a choice about whether they should be merged (decision: yes)
3. Merge this repo's functionality into XBlock, including doc updates. Consider including an ADR. Cut a major XBlock release.
4. Update this repo to just be thin compatibility layer which imports from XBlock. Cut a final release of it.
5. Mark this repo as deprecated (no DEPR ticket necessary) and archive it
6. Announce the change

[bradenmacdonald]

@kdmccormick Thanks for bringing this up. I think it's an excellent idea to merge this into XBlock. I think I can answer some historical questions for you.

understand why the two libraries were separate in the first place

I believe xblock-utils was created by OpenCraft. At the time we were creating tons of XBlocks, so it was a repo that held common code/patterns for use in our various XBlocks. I suspect that we kept it separate so we could iterate on it rapidly, as at the time it took too long to get things merged into Open edX core repos like XBlock or edx-platform. At some point, other XBlock developers and eventually even core platform XBlocks started using the xblock-utils library. Over time, this awkward split was never really properly re-evaluated as you're doing now.

XBlock doesn't depend on Django
I can't find the ADR, but somewhere we decided that Django should be assumed for XBlocks, since enforcing Django-agnosticness wasn't yielding any value.

AFAIK XBlock was originally intended to be "portable" to other LMSs, but since it is python based, it can only really work with other python-based LMSs, and the only one that it ever actually worked with or was designed to work with was Google Course Builder via coursebuilder_xblock_module. Since Course Builder was not Django-based, XBlock had to be Django-free. However, that project didn't last very long and nobody has been using XBlocks in anything other than Open edX for many years at this point, to the best of my knowledge. So I don't see any reason to avoid assuming Django in XBlock code anymore.

[kdmccormick]

@bradenmacdonald That's really helpful context, thanks! I'm convinced at this point that we should merge them; I've updated this ticket's AC capture that.

[farhan]

Here is the XBlock repo PR to merge this library into it
#669

[farhan]

Progress update:

• The xblock-utils library has been moved with unit test cases.
• Integration tests of the library have been dropped because of the deprecation of bok-choy library.

Below 3 tasks are pending:

1. Passing tox test cases on github-actions. They are passing locally. Xblock repo run test cases on pip package rather than project files. On GitHub actions pip package is missing some data files that are required in test cases. Currently looking into it.
2. After removing of bok-choy test cases, code coverage falls below the required target which needs to write missing test cases. Majorly for studio_editable.py file
3. Need to move the documentation as well (either in readme or sphinx docs)
   https://github.com/openedx/xblock-utils#more-documentation

@feanil We can cover points 2 and 3 in separate stories. Should I create one for them?

[farhan]

Passing tox test cases on github-actions. They are passing locally. Xblock repo run test cases on pip package rather than project files. On GitHub actions pip package is missing some data files that are required in test cases. Currently looking into it.

Above point 1 has been fixed by updating the setuptools

56c2a8b

[feanil]

@farhan I think it's fine to create separate stories for Points 2 and 3. For the documentation, you should move it to be a new sphinxs docs under XBlock/docs.

[farhan]

PR for docs shifting:
#672

[farhan]

I am deprecating the xblock-utils repository within the scope of this ticket

Here is the PR: openedx-unsupported/xblock-utils#231

[feanil]

The xblock-utils repo has been archived and moved to the openedx-unsupported org. I moved this issue to the XBlock repo so that it can retain the history of this move.

[kdmccormick]

Some follow-up: open-craft/xblock-poll#127