0003: Derive the shapes from the topic, at pinned releases
Decision: every shape of this repository will derive from the topic of reader-ergonomics-topic, and both parents are linked and run at a release's commit: reader-ergonomics v1.18.2 and reader-ergonomics-topic v0.4.0.
Status: accepted, 2026-10-29; its last point superseded by 0004, which runs the topic check in CI. Shape: decision record.
Context
- The topic is a base for genre shapes: a title, a summary, a body, contents and see also, and a shape adds blocks without removing any (topic).
- Its first derived shape was the decision record. Since v1.3.0 the standard holds a general one, which this repository's records follow.
- The extension contract asks an extension to pin the standard by commit, never by tag (extending.md).
Decision
- A lesson, an exercise sheet, a study guide or a deck will be a topic with blocks of its own.
- Each block takes a name from the topic's table of accepted names, and each document links the shape it follows.
- Links down to either parent carry the release's commit. CI checks out reader-ergonomics at
bfbe9f7(v1.18.2). - The topic check is not run here yet: it reads the shapes, and none is written. It joins CI with the first shape. (Superseded: 0004 wrote the shapes, and CI has run the check since.)
Consequences
- Study documents read like every other document of the family, at every depth.
- A change in either parent reaches this repository only when its pin moves, by a record here.
- If a study document needs a block the topic forbids, the conflict goes to reader-ergonomics-topic, not around it.