diff --git a/.githooks/pre-commit b/.githooks/pre-commit new file mode 100755 index 0000000..3ee8e45 --- /dev/null +++ b/.githooks/pre-commit @@ -0,0 +1,17 @@ +#!/bin/sh +# Pre-commit gate for the T-Deck workspace: run the fast headless test layer +# (unit + integration, deterministic, seconds) before every commit, so a +# regression can never land silently. +# +# skip once: git commit --no-verify +# disable: git config --unset core.hooksPath +# (re)install: make hooks + +echo "[pre-commit] running fast tests (make netdeck-test-unit)..." +make netdeck-test-unit || { + echo "" >&2 + echo "[pre-commit] FAST TESTS FAILED - commit aborted." >&2 + echo " Fix the failures above, or bypass once with: git commit --no-verify" >&2 + exit 1 +} +echo "[pre-commit] fast tests OK" diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..298efc3 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,34 @@ +# T-Deck workspace — agent notes + +## Toolchain + +- platformio `pio` is in `~/.platformio/` (`~/.platformio/penv/bin/pio`), or + on `PATH` if available. + +## Build & test — one command each, from the repo root + +- `make netdeck` — builds BOTH targets of the app: ESP32-S3 firmware + (pio) and SDL2 emulator. Both must stay green. +- `make netdeck-test` — full headless test suite: unit + integration + (fast, deterministic) + E2E journeys (separate build, ~1-2 min). +- `make netdeck-test-unit` — fast layer only (unit + integration, seconds). +- `emulator/tests/README.md` — how the test layers work and how to add + tests (unit/integration headers, E2E journeys). + +## Git hooks + +A pre-commit hook runs the fast test layer (`make netdeck-test-unit`) +before every commit. Hooks are not versioned inside `.git/hooks`; this +repo ships them under `.githooks/`. Enable with: + + make hooks # = git config core.hooksPath .githooks + +- Bypass once with `git commit --no-verify` (use sparingly, say why). +- Disable: `git config --unset core.hooksPath`. + +## Commit discipline + +- Feature/increment commits: `make netdeck` (dual build) + the relevant + test layer must pass before committing. +- Milestone commits: run `make netdeck-test` (full suite) and update + `src/netdeck/STATUS.md` in the same commit. diff --git a/Makefile b/Makefile index 8a716d7..f43b264 100644 --- a/Makefile +++ b/Makefile @@ -7,8 +7,11 @@ # unit + integration (fast, deterministic) # + E2E journeys (separate build, real loop(), # ~1-2 min wall time) -# make netdeck-test-unit fast layer only +# make netdeck-test-unit fast layer only (unit + integration, seconds) — +# also what the pre-commit hook runs # make netdeck-test-e2e E2E layer only +# make hooks enable the pre-commit hook for this clone +# (= git config core.hooksPath .githooks) # # Firmware builds need platformio: either `pio` on PATH or the default # ~/.platformio/penv/bin/pio install. @@ -37,4 +40,10 @@ netdeck-test-unit: netdeck-test-e2e: $(MAKE) --no-print-directory -C emulator APP=NetDeck test-e2e -.PHONY: netdeck netdeck-test netdeck-test-unit netdeck-test-e2e +# install the pre-commit hook into this clone (hooks are not versioned in +# .git/hooks; the repo ships them under .githooks/ instead) +hooks: + git config core.hooksPath .githooks + @echo "pre-commit hook enabled: make netdeck-test-unit runs before every commit" + +.PHONY: netdeck netdeck-test netdeck-test-unit netdeck-test-e2e hooks