From 6979b1a2b88e204911fae26999204076a46daeca Mon Sep 17 00:00:00 2001 From: Duncan Tourolle Date: Sat, 26 Sep 2026 07:46:17 -0400 Subject: [PATCH] Tell contributors about the key and manual gates CONTRIBUTING named four CI commands and the traceability tag, and nothing about the three checks added since 0.14.1 that a first UI change is most likely to meet: gestures-check, which fails on a key bound without a GESTURE block or a block naming an unbound key (9d1e31f); manual-check, which fails when index.html is not the render of the manual (1021635); and record.sh --check, which fails when the manual shows a picture no scene makes (70583b9). Two short paragraphs say what each holds and where the recording tools are. --- CONTRIBUTING.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c8ab36c..ff3a309 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -130,6 +130,24 @@ strength of plumbing a future feature would use. So: **close a requirement with a test that would fail if the behaviour were removed.** Coverage that moves slowly and means something beats coverage that moves quickly. +**Keys and gestures are held the same way.** A key handler in Slint compares +one canonical chord, `Keys.chord(event) == "Ctrl+Z"`, under a `// KEYMAP:` +comment naming its section of the gesture book, and every key it binds must be +named by a `GESTURE:` block beside it. `cargo run -p traceability -- gestures` +regenerates [`docs/gestures.md`](docs/gestures.md) and the in-app help sheet +from those blocks; `-- gestures-check` fails when a handler binds a key no tag +names, or a tag names a key no handler binds. A `manual:` field in a block +links the gesture to a section of the manual, and a heading that is not there +fails the scan. + +**The manual is checked too.** `docs/manual/index.html` is rendered from +`docs/manual/README.md` by `-- manual` and `-- manual-check` fails when they +differ; `tools/manual/record.sh --check` fails when the manual shows a picture +no scene in `tools/manual/scenes.py` makes. If you change what a pictured +screen looks like, [`tools/manual`](tools/manual/README.md) says how to record +it again. The pre-commit hook regenerates the matrix, the gesture book and the +page; CI runs all three checks. + ## Two invariants the build defends Worth knowing before you trip one, because both failures name a requirement