kmccormick
September 4, 2024, 3:59pm
1
We are making a breaking change to the XBlock framework. This will only impact operators who have developed custom XBlock runtimes outside of edx-platform.
The only custom runtime that we know exists is the xblock-sdk (“XBlock Workbench”), which Axim will take care of fixing. We honestly don’t think that any other runtimes exist. If you do have a custom XBlock runtime, though, please reach out, and we can help you understand the change.
The comment period ends in week on Wendesday 11 September . We’re excited for this change because it will allow us to add type annotations to the XBlock framework as part of the Sumac release!
opened 06:10PM - 27 Aug 24 UTC
depr
_**In other words: Starting with XBlock 6.0.0, we will assume that XBlock Scope … IDs are instances of OpaqueKey.**_
(Most if not all people can ignore this DEPR. Only operators with entirely custom XBlock Runtime implementations need to pay attention. We're actually not aware of any such custom Runtime implementations currently, so this DEPR is most likely just a formality.)
### Proposal Date
2024-08-27
### Target Ticket Acceptance Date
2024-09-10
### Earliest Open edX Named Release Without This Functionality
Sumac (master: Late Sept 2024)
### Rationale
#### History
[edx-platform](https://github.com/openedx/edx-platform/commits/master/?after=2e77e65d1c034a7e929d284c99f8bc5b0b1f0025+65610) was created circa 20211 and the [XBlock framework](https://github.com/openedx/xblock) was created circa 2012. Originally, those systems used carefully-formatted strings (`str` instances) to identify XBlocks in various contexts:
* course runs,
* usages of blocks across the site, and
* definitions of XBlocks content.
Circa 2014, in order to deal with the fragility and complexity of those strings in the light of a major overhaul of edx-platform's MongoDB schema (from "old" ModuleStore to "split" ModuleStore), we created the [opaque-keys](https://github.com/openedx/opaque-keys/) package. An OpaqueKey is a value object which identifies an XBlock scope and has a well-defined string representation; each subclass of OpaqueKey identifies a different kind of scope. Specifically, in this new system:
* Course runs are identified by CourseKeys (and, more generally, LearningContextKeys).
* Usages of blocks are identified by UsageKeys.
* Definitions of block content are identified by DefinitionKeys.
edx-platform was completely migrated over from string IDs to OpaqueKey IDs and has exclusively used opaque-keys for the past decade.
However, this migration was never represented in the XBlock framework. In theory, any object can be used as an XBlock scope ID. XBlock tests still use string IDs, as does the [xblock workbench](https://github.com/openedx/xblock-sdk/). In practice, though, **edx-platform is the only production XBlock runtime that any of us are aware of**, so in the real world XBlocks are all running with OpaqueKey scope IDs rather than string scope IDs.
#### Rationale for now assuming that scope IDs are OpaqueKeys
As an XBlock developer, it is confusing that the XBlock documentation makes no mention of OpaqueKeys, and it is strange and unhelpful that the XBlock Workbench identifies blocks in a way that is inconsistent from edx-platform.
Furthermore, [we are adding type annotations to the XBlock package](https://github.com/openedx/XBlock/issues/707). The type annotations would be significantly less potent and instructive if they had to support string IDs: they would all be typed as `object` or `Any`, so edx-platform would need to disable mypy with `# type: ignore` wherever it treated an ID is an OpaqueKey. However, once we assume that scope IDs are all OpaqueKeys, we can annotate various XBlock API signatures with `LearningContextKey`, `UsageKey`, `DefinitionKey`, etc.. This will allow for stronger correctness checking in CI, better documentation for core and plugin developers, and more accurate code intelligence for developers using IDEs.
### Removal
Beginning in XBlock 6.0.0:
* XBlock API calls may raise if given usage ids which are not instances of `opaque_keys.edx.UsageKey`.
* XBlock API calls may raise if given definition ids which are not instances of `opaque_keys.edx.DefinitionKey`.
* `MemoryIdManager` will generate instances of `UsageKey` and `DefinitionKey`, as appropriate, rather than `str`.
### Replacement
N/A
### Deprecation
In the interest of making it easy to update unit tests, we will make the XBlock API raise obvious assertion errors wherever the new scope-IDs-are-OpaqueKeys assumption is violated.
We do not plan to raise warnings ahead of time. We believe that only the XBlock Workbench (xblock-sdk) is in violation of this assumption, and Axim will take care of fixing it.
### Migration
If any production XBlock Runtimes exist using string scope IDs, those IDs can be substituted with OpaqueKey instances whose `__str__` methods generate identical scope IDs. We do not expect any such Runtimes to exist, though. If you know of one and need help understanding the migration, please reach out.
### Additional Info
None
### Task List
#### edx-platform repo
Constrain XBlock to < 6:
```
# Date: 2024-mm-dd
# Description: XBlock>=6 drops support for string scope IDs. We expect that this will
# not break any edx-platform app code, but we should smoke-test that expectation, and
# we may need to fix some unit tests that use string scope IDs.
# Ticket: https://github.com/openedx/XBlock/issues/784
XBlock[django]<6
```
#### XBlock repo
- [ ] Update unit tests to use OpaqueKeys instead of strings for scope IDs.
- [ ] Add `assert` statements to certain constructors to ensure that IDs are OpaqueKeys.
- [ ] Update [MemoryIdManager](https://github.com/openedx/XBlock/blob/19e752784a592a1813132eaa00e6e9e24804669e/xblock/runtime.py#L360) to generate OpaqueKeys instead of strings.
- [ ] Update XBlock documentation as necessary.
- [ ] Release XBlock version 6.0.0.
- [ ] Remove this bit from xblock/core.py: https://github.com/openedx/XBlock/blob/19e752784a592a1813132eaa00e6e9e24804669e/xblock/core.py#L442-L444
- [ ] _Either as part version 6.0.0 or in a follow-up as 6.1.0:_ Type-annotate the entire XBlock API.
#### xblock-sdk repo
- [ ] Update the workbench's XBlock Runtime to use string scope IDs rather than OpaqueKey scope IDs.
#### back to the edx-platform repo
- [ ] Update certain unit tests to use OpaqueKeys instead of strings for scope IDs.
- [ ] Ensure that the change to MemoryIdManager [has not affected its usage in the Learning Core](https://github.com/openedx/edx-platform/blob/c65478e487e98042af99bbab3243efb9abfaad74/openedx/core/djangoapps/xblock/runtime/runtime.py#L444) runtime for Content Libraries.
- [ ] Remove the constraint and upgrade to XBlock==6.0.0