docs: schema 2.1 guide, codes, changelog, and report
A guide page for the four registries: where entries live, how targets point at them, the other new fields, the brace-reference table, what students never see, the lecture and glossary pages, every new error and lint rule, and the migration from terms.yaml and values.yaml. The setup guide points at it. The README covers glossary.yaml, the nine schemas, the 2.1 checks, the glossary lint family and the note severity, the new lecture commands and report sections, migrate glossary, and schema version 2.1. Module docs and the changelog follow. docs/design/2.1/CODES.md maps the specification's E, W, and I codes to coursebank's messages and lint codes, each with its test, and REPORT.md records what changed, the two remaining schema differences, every choice made where the specification left room, and suggested changes to it. A new test covers the validation messages the specification does not number. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
11 files changed
+535
-29
No files matched your search
@@ -0,0 +1,98 @@
|
||||
# coursebank 2.1: implementation report
|
||||
|
||||
Branch `schema-2.1`, six commits, one per phase, nothing pushed.
|
||||
Every phase ended with `cargo fmt`, `cargo clippy --all-targets -- -D warnings`, `cargo test`, and `cargo doc --no-deps` clean.
|
||||
The 2.1 work adds 57 integration tests (schema 7, validate 18, lint 19, render 8, migrate 5) and 14 unit tests, and every existing test still passes unchanged.
|
||||
|
||||
## What changed, by phase
|
||||
|
||||
| Phase | Commit | Files |
|
||||
|---|---|---|
|
||||
| 1. Types and schemas | `51a2fd2` | `src/model/course/glossary.rs` (new: every entry type, `RefKind`, the brace scanner), `src/model/course.rs` (the four registries, new fields on objectives, targets, lectures, readings, policy; `SCHEMA_VERSION = "2.1"`), `src/model/course/fragment.rs` (four sections, `Role::Glossary`, `glossary.yaml`), `src/model/layout.rs`, `src/model/item.rs` (`misconception_id`), `src/authoring/jsonschema.rs` (`Kind::Glossary` and every changed builder), `tests/schema_2_1.rs`, `tests/docs.rs` |
|
||||
| 2. Validation | `960cf6c` | `src/model/course/glossary.rs` (`glossary_problems`: E2101 to E2107 and the prefix check), `src/model/bank.rs` (E2108), `Cargo.toml` (`regex`), `tests/validate_2_1.rs`, `tests/common/mod.rs` |
|
||||
| 3. Lint | `b8fdf4d` | `src/authoring/lint.rs` (14 rules, `glossary` family; two existing rules accept `misconception_id`), `src/authoring/lint/glossary.rs` (new), `src/model/catalog.rs` (`Severity::Note`), `src/cli.rs`, `src/commands/project.rs` (notes never fail lint), `tests/lint_2_1.rs` |
|
||||
| 4. Derived data and rendering | `50a1e08` | `src/model/course/glossary.rs` (first use, teaching order, `expand_refs`), `src/export/lecture.rs` (`page_markdown`, `glossary_markdown`, brace rendering), `src/cli.rs` and `src/commands/lectures.rs` (`lecture page`, `lecture glossary`), `src/analysis/students.rs`, `src/export/report.rs`, `src/analysis/diagnostic.rs`, `src/export/typst/diagnostic.rs`, `src/export/typst/templates/student-report.typ`, `tests/render_2_1.rs` |
|
||||
| 5. Migration | `6c07122` | `src/migrate/glossary.rs` (new), `src/migrate.rs`, `src/cli.rs`, `src/commands/project.rs`, `tests/migrate_2_1.rs` |
|
||||
| 6. Documentation | this commit | `docs/guide/glossary.md` (new) and `src/guide.rs`, `docs/guide/setup.md`, `README.md`, `CHANGELOG.md`, module docs in `src/lib.rs`, `src/model.rs`, `src/authoring.rs`, `docs/design/2.1/CODES.md`, this file, one more test in `tests/validate_2_1.rs` |
|
||||
|
||||
The rendered example lecture page was sent as a private artifact in Phase 4.
|
||||
|
||||
## Code mapping
|
||||
|
||||
In `CODES.md`. In short: E2101 to E2108 are validation messages without codes, as every coursebank error is; W2101 to W2111 are the `glossary-*` lint rules; I2112 and I2113 are `glossary-defined-elsewhere` and `glossary-proposed` at a new `note` severity.
|
||||
Two additions: a prefix error next to E2101, and the lint rule `glossary-unresolved-reference` that takes E2106's place in 2.0 reading fields.
|
||||
|
||||
## Generated versus target schemas
|
||||
|
||||
The schemas are not generated from the Rust types: `src/authoring/jsonschema.rs` writes each one by hand with `serde_json::json!`, and that was the case before 2.1.
|
||||
So rule 2 became: port every edit in `build_schemas.py` into those builders, with the descriptions copied word for word.
|
||||
Hand-written JSON can say `propertyNames`, so the id patterns are in the schemas; the validator also enforces them, because nothing checks YAML against the JSON Schema at load time.
|
||||
|
||||
`tests/schema_2_1.rs` compares each of the nine generated schemas with `docs/design/2.1/schemas/` as JSON values. Two differences remain, both older than 2.1 and both one word:
|
||||
|
||||
| File | Path | Generated | Target |
|
||||
|---|---|---|---|
|
||||
| `calibration.schema.json` | `/properties/items/additionalProperties/properties/variants/items/properties/option_stats/description` | behaviour | behavior |
|
||||
| `course.schema.json` | `/properties/policy/properties/grade_scale/items/properties/group/description` | Colour | Color |
|
||||
|
||||
`schemas-original/` has the American spellings, which no commit in this repository ever had.
|
||||
I kept the code's spelling; a test fails if either difference disappears or another appears.
|
||||
|
||||
## What I did differently from the specification, and why
|
||||
|
||||
1. **Lecture files and `references.yaml` cannot define glossary entries.** The specification says any fragment may; the target schemas add the registries only to `course`, `objective`, and `glossary`, and I followed the schemas. A lecture file that tries gets the existing "a section belongs to a kind of file" error.
|
||||
2. **Teaching order is coursebank's: lectures in id order.** The prototype sorts lectures by `(date, id)`. The specification says to use the existing order, which is the lecture map's id order. They agree on the example.
|
||||
3. **E2106 on 2.0 fields (Q2, option b).** The four new prefixes are errors everywhere. An unresolved `{lo-…}` or `{t-…}` in a reading's `summary`, `focus`, or `skip` stays a medium lint finding, because 2.0 accepted it and rule 1 says no new errors.
|
||||
4. **Note severity (Q3).** `glossary-defined-elsewhere` and `glossary-proposed` are notes. `lint --min-severity` now defaults to `note`, and `lint` exits 2 only when something is above a note, so a course with proposed entries passes a lint gate.
|
||||
5. **`regex` crate (Q1).** Built without default features (`std`, `unicode-perl`, `unicode-case`). No look-around and no backreferences; such a pattern fails E2107 with the crate's reason.
|
||||
6. **The preview's `(T t-align-fill-matrix)` renders as `(T 3)`**, the target's number on the page, as 2.0's readings page always did. The prototype prints the raw id.
|
||||
7. **Three lines the preview does not have.** The page prints "About 40 minutes of assigned reading." above the readings, and each reading's `summary` and `skip`, which the 2.0 readings page prints and the specification's "readings (with minutes)" does not rule out. The snapshot test allows exactly these three.
|
||||
8. **Anchors are `glossary-<id>`**, such as `#glossary-term-gap`, not `#term-gap`. Quarto reserves the `eq-` prefix for numbered equations, so `{#eq-global-recurrence}` would be read as an equation cross-reference.
|
||||
9. **Report wording.** An option's own `misconception` text keeps its 2.0 sentence. An option with only a `misconception_id` prints "This answer reflects a common mistake: *belief*", then the correction. Misses sharing one are grouped under "The same mistake, more than once" with their question numbers. The registry belief and correction are student-facing by design, so they print without `--misconceptions`; the option's own text keeps that switch.
|
||||
10. **Two existing lint rules changed.** `complete-distractor-design` accepts a `misconception_id` as design, and `complete-student-feedback` accepts one that resolves, since the correction is the feedback.
|
||||
11. **`policy.exam_conditions` and `policy.blueprints` are stored and validated, but nothing reads them.** No phase asked for it. `assemble --blueprint NAME` reading `policy.blueprints` is a small follow-up.
|
||||
12. **More errors than E2101 to E2108.** Required text that is present but empty, a material without a URL, `minutes: 0`, level keys outside 1 to 5, and non-positive durations. They follow from the schemas, cannot fire on 2.0 data, and are listed in `CODES.md`.
|
||||
13. **Proposed entries look approved to students.** Nothing on a student page says "proposed"; the rule-5 test checks the word never appears.
|
||||
14. **The example needed one edit.** The bank item had no `status`, which coursebank requires; I added `status: draft` with a comment. With `approved`, validation would also require `cognitive_process`, `sources`, and `design`.
|
||||
15. **The value `say: 'about 10^{59}'` renders literally**, caret and braces, because `say` is printed as written and the example does not put it in math markup.
|
||||
16. **The prototype was read, not run.** `pyv` has no vendored PyYAML on this machine, so `check21.py --selftest` could not run. Each self-test mutation became a test, built by reading the prototype.
|
||||
17. **Migration details the specification leaves open:**
|
||||
- a value's `term:` gains the prefix of the id it names, and is reported;
|
||||
- fields 2.1 has no place for are dropped and reported;
|
||||
- an existing `glossary.yaml` is added to as text, never rewritten;
|
||||
- entries declared anywhere in the course are skipped, so a second run is a no-op;
|
||||
- an id that would be invalid with its prefix, two entries that would share an id, and an id another registry already uses are refused before anything is written;
|
||||
- an entry written as a flow mapping is written by the serializer instead of copied.
|
||||
|
||||
On the example, `coursebank lint` reports the two expected glossary findings and one existing finding: `cue-absolute` on option `o-length`, which says "always".
|
||||
|
||||
## Running the migration on your course
|
||||
|
||||
From the course root, with the 1.0 files wherever they are:
|
||||
|
||||
```console
|
||||
$ coursebank migrate glossary --terms terms.yaml --values values.yaml --dry-run
|
||||
$ coursebank migrate glossary --terms terms.yaml --values values.yaml
|
||||
$ coursebank validate
|
||||
$ coursebank lint --only glossary-unused,glossary-defined-elsewhere,glossary-proposed
|
||||
```
|
||||
|
||||
The dry run prints the report and the file it would write.
|
||||
The report lists renamed ids, every dropped `first` or `lectures` that the targets now contradict, entries no target lists yet, and fields dropped.
|
||||
Before you link any targets, every entry will be under "no target lists these yet", and every old `first` and `lectures` will be reported as contradicted, because nothing lists the new ids yet.
|
||||
`terms.yaml` and `values.yaml` are left in place.
|
||||
Then add the ids to each target's `terms` and `values`, and move each entry into the objective file that first needs it; `glossary-defined-elsewhere` names those files.
|
||||
|
||||
## Suggested changes to the specification
|
||||
|
||||
1. Say which fragments may define entries: objective files, `glossary.yaml`, and `course.yaml`, as the schemas already do, rather than "any fragment".
|
||||
2. Define teaching order: lectures by id or by date. The prototype and the spec's "existing order" differ for a course whose lecture ids do not sort by date.
|
||||
3. Write down E2106's exemption for 2.0 reading fields, so rule 1 and E2106 do not contradict each other.
|
||||
4. Define the I-codes' effect on exit status: shown, never failing.
|
||||
5. Say whether `say` is plain text or markup. If markup, the example should write `about $10^{59}$`.
|
||||
6. Give the anchors a prefix of their own (`glossary-`), and note that Quarto reserves `eq-`, `fig-`, `tbl-`, and `sec-`.
|
||||
7. Make `lecture-page-preview.md` print target numbers (`T 3`) rather than raw ids, and decide whether a reading's `summary` and `skip` belong on the page.
|
||||
8. Add `status:` to the example bank item, since coursebank requires it.
|
||||
9. Name the regular-expression dialect as the subset Python's `re` and Rust's `regex` share: no look-around, no backreferences.
|
||||
10. In the migration table, add a value's `term:` (prefix it) and say what happens to unknown fields and to an existing `glossary.yaml`.
|
||||
11. Decide whether `policy.blueprints` should feed `assemble`, and say so; today it is data with no reader.
|
||||
Reference in new issue
Block a user