// Backwards compatibility rules when changing element controllers in `apps/prairielearn/elements/`.
Conventions for writing tRPC routers and procedures in PrairieLearn.
Keeping the AI question generation HTML validator in sync with element implementations.
Write end-to-end browser tests using Playwright.
Dealing with groups and teams in PrairieLearn, and confusion about table/column/variable names.
| name | element-backwards-compat |
| description | Backwards compatibility rules when changing element controllers in `apps/prairielearn/elements/`. |
Several dict-shaped fields on the data dict that an element controller receives are persisted to the database and read back by future invocations. Existing variants and submissions are not re-generated when element code changes, so any new key added to a persisted dict will be missing on rows written before the change. Reading it with dict[key] throws KeyError and breaks every existing question that uses the element. This has happened twice in pl-order-blocks alone (ordering_feedback, initially_placed).
The persisted dict-shaped fields are:
data["params"], data["correct_answers"].data["submitted_answers"], data["raw_submitted_answers"], data["partial_scores"], data["feedback"], data["format_errors"].Adding a new key to a persisted dict? Every reader in every element function must use dict.get(key, default) with a sensible default, never dict[key]. This applies to top-level keys and to keys inside any nested per-block / per-answer dict stored inside a persisted field. If the element uses a TypedDict for the nested shape, mark the new field NotRequired[...] from typing so pyright catches unguarded reads.
Renaming, removing, or changing the semantics of a persisted key? Don't. Keep the old key alongside the new one and have readers fall back to it when the new one is missing. Old rows still hold the old shape forever.