diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 19a9943..4ffb8e2 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -8,12 +8,21 @@ ## Testing - + + +## Hardware + + ## Checklist +- [ ] Opened as a draft; the Hardware section above is filled in before marking ready - [ ] Tests pass locally (`python -m pytest -q`) - [ ] Added or updated tests for the change - [ ] Updated documentation if behavior or the public API changed diff --git a/CLAUDE.md b/CLAUDE.md index eb7f794..3d6e866 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -33,6 +33,7 @@ Read `docs/STEERING.md` before non-trivial work (new operations, transport or fr - Hardware sessions: quit Cortex Control first - it holds the HID interface exclusively. - Describe the protocol work as documenting the device's protocol as-is (recovered schema, observed traffic). Do not call it "reverse engineering" in docs, comments, commit messages, or issues. - Changed code under a path listed in `docs/STEERING.md` § Owned Paths? Diff and update STEERING/CLAUDE/ADR in the same PR. +- A pull request opens as a DRAFT (`gh pr create --draft`). It is marked ready only after `pytest tests/hardware --hardware` has run on its final commit, with the commit hash, the unit's CorOS version, the `operations on ...` block and pytest's last line in the description - or after the human has waived the run explicitly in the description, which they may do for a change that cannot reach the wire. The offline suite and mypy are not a substitute: they prove the library agrees with itself, not that it agrees with the unit. PR #53 is the evidence: the 2026-09-07 post-merge run found two stale records that a green offline suite had passed. Never waive the run yourself, and never present a pull request as ready that has not been through this. `contributing.md` § "Before you mark a pull request ready" states the rule for contributors, with one more state for a contributor who has no unit (say so, mark ready, a maintainer runs it before merging); you always work where the unit is, so that state is not yours. ## Do not diff --git a/contributing.md b/contributing.md index adfbbb6..3dcab7c 100644 --- a/contributing.md +++ b/contributing.md @@ -16,12 +16,17 @@ You do **not** need to ask for access or to be added to the project first. The f 1. **Fork** this repository to your own account. 2. Create a **branch** for your change. -3. Commit your work, push it to your fork, and open a **pull request** against `main`. +3. Commit your work, push it to your fork, and open a **draft pull request** against + `main`. Mark it ready for review once the checks under "Before you mark a pull + request ready" below have run, or the description says why they could not. 4. A maintainer reviews it. Every change is reviewed and approved before it is merged, so please be patient and expect a round or two of feedback. -Continuous integration runs the test suite on every pull request. Please make sure it -is green - a red build will block the merge. +Continuous integration runs the offline suite, mypy and a packaging build on every +pull request. Please +make sure it is green - a red build will block the merge. Green proves the library +agrees with itself; only a unit proves it agrees with the device, which is why the +hardware suite below is part of every pull request too. ## Development setup @@ -95,7 +100,9 @@ Two contracts the tests protect, worth knowing before you change import structur ## Working with hardware -If your change touches the live device path and you want to verify it on a real unit: +Every pull request runs the hardware suite before it is marked ready (see "Before +you mark a pull request ready" below). To run it, or to verify anything else on a +real unit: - Connect the Quad Cortex over **USB**. (Wi-Fi may stay on; it makes no difference.) - **Quit Cortex Control first.** It holds the USB interface exclusively, so nothing @@ -107,9 +114,36 @@ If your change touches the live device path and you want to verify it on a real (ADR-0020): record what you measure beside the 4.0.1 record in `docs/protocol.md`, dated and named by CorOS version, rather than in its place. -When you confirm behavior on hardware, say so in the pull request: which operation, -which CorOS version, and how you verified it (a read-back, or watching the unit). -That evidence is what keeps [docs/protocol.md](docs/protocol.md) trustworthy. +### Before you mark a pull request ready + +A pull request opens as a draft and is marked ready for review only after the +hardware suite has run on its final commit: + +```bash +pytest tests/hardware --hardware +``` + +The prerequisites are the ones above plus the hidapi library from "Development +setup". On macOS prefix the command with `DYLD_LIBRARY_PATH=/opt/homebrew/lib`. On +a unit the registry refuses (a firmware no profile has measured, or a Mini) add +`--profile` with the class to measure as (see "Adding a device profile"). + +Put four things in the pull request description: the short commit hash the run was +made on, the CorOS version of the unit, the `operations on ...` block the suite +prints, and pytest's own last line after it (the one with the pass, fail, error and +skip counts). If +your change adds or alters an operation, also say how you verified that operation on +the unit (a read-back, or watching the screen), because the suite measures only the +operations a hardware test names. This record is the evidence this project keeps: +the offline suite proves the library agrees with itself, and a unit is what proves +it agrees with the device. + +If you have no unit, say so in the description and mark the pull request ready +anyway; a maintainer runs the suite before merging. If the change cannot reach the +wire (documentation, packaging), a maintainer may waive the run, in the description. +Either way the description says which it was: run, with the numbers, or not run, +with the reason. A description that says nothing about hardware is not ready for +review, whatever GitHub shows. ## Adding a device profile diff --git a/docs/STEERING.md b/docs/STEERING.md index 69e123d..b11fc33 100644 --- a/docs/STEERING.md +++ b/docs/STEERING.md @@ -56,7 +56,7 @@ The model layer holds the state (design in [`domain-model.md`](domain-model.md) | Pattern | What | Why (or `see ADR-000N`) | Canonical example | When the pattern does not apply | |---------|------|-------------------------|-------------------|----------------------------------| | Layered message flow | New operations are a registry entry plus a thin `QuadCortex` method that builds a protobuf and picks `send`/`request`/`await_broadcast` | Wire concerns stay below `client.py`, which keeps the whole API testable with a fake transport (see ADR-0002) | `QuadCortex.switch_scene` in `pyquadcortex/protocol/client.py` | `cli.py`'s `version` subcommand deliberately bypasses the connect handshake (`_open_unconnected`) | -| Fake-per-layer offline tests | Each layer has a purpose-built double: golden captured frames for `framing`, `FakeHid` for `transport`, `FakeTransport` for `client` | see ADR-0002 | `FakeTransport` in `tests/test_client.py` | Hardware verification happens manually via `examples/`, outside the suite | +| Fake-per-layer offline tests | Each layer has a purpose-built double: golden captured frames for `framing`, `FakeHid` for `transport`, `FakeTransport` for `client` | see ADR-0002 | `FakeTransport` in `tests/test_client.py` | Hardware verification is `tests/hardware` behind `--hardware` (ADR-0005), run on every pull request before it is marked ready (contributing.md) | | Evidence-bearing docstrings | Each operation's docstring states what is confirmed on hardware vs inferred from the schema | The device gives no errors for wrong writes, so recorded evidence is the only trail | `QuadCortex.read_preset` in `pyquadcortex/protocol/client.py` | Non-protocol helpers (pure functions) carry ordinary docstrings | | Keyed grid edits | Mutations are row/column-keyed `Grid` UPDATEs | The device applies grid updates by key; wholesale preset writes are silently ignored (see [`architecture.md`](architecture.md), "write_preset is a trap") | `QuadCortex.set_bypass` in `pyquadcortex/protocol/client.py` | Read paths, and non-grid operations | | One translation boundary | Screen values become wire values in exactly one PACKAGE, and a source-reading test proves no other module in the package does it - the whole package outside `protocol/`, not just `device/`. The exemption covers a directory, so a test names the package's modules and a new one has to come through that list | An off-by-one row is silent - the write lands on a real row and reads back perfectly - so a convention cannot be trusted to hold (design principle 5 in [`domain-model.md`](domain-model.md)) | `pyquadcortex/device/translate/` | The protocol layer, which keeps its zero-based COORDINATES. Its scales come from the catalog, and quoting the device's own units is not translating - see ADR-0016 | @@ -119,7 +119,7 @@ None yet. Protocol unknowns (the splitter write path, the IR import payload form - **PyPI** for releases (process and credentials handling in [`releasing.md`](releasing.md)) - **GitHub Actions** for the offline suite on every PR (`.github/workflows/ci.yml`) - **hidapi** as the OS-level native library on any machine that talks to hardware -- **One physical Quad Cortex** (CorOS 4.0.1 / d14e) - the scarce resource; hardware verification is manual and serialized on it +- **One physical Quad Cortex** (CorOS 4.0.1 / d14e) - the scarce resource; the hardware suite runs on it before every pull request is marked ready, so runs are serialized ### Workload characteristics @@ -138,6 +138,27 @@ Single-device, single-connection USB HID at interactive rates (129-byte reports) ## Change Log +### 2026-09-07 - A pull request is a draft until the hardware suite has run on it + +**What changed:** `contributing.md` gains "Before you mark a pull request ready": +a pull request opens as a draft, the hardware suite runs on its final commit, and +the description records the commit hash, the CorOS version, pytest's summary line +and the `operations on ...` block. A contributor with no unit says so and a +maintainer runs the suite before merging; a maintainer may waive the run, in the +description, for a change that cannot reach the wire. The pull request template +gained a Hardware section with those three states, `CLAUDE.md` states the rule for +the agent, and the section 5 pattern row that said hardware verification happens +manually via `examples/` now names the suite. + +**Why:** the 2026-09-07 post-merge run (PR #53) found two stale records that a +green offline suite had passed, and two pull requests that week were marked ready +without the run. A rule that lives only in memory is skipped under time pressure; +one that lives in the template and the contributor guide is not. + +**Scope of impact:** +- **Updated:** contributing.md, CLAUDE.md, .github/PULL_REQUEST_TEMPLATE.md, STEERING.md sections 5 and 10 +- **Not updated (intentionally):** ADR.md - this is process, not an architectural decision; ci.yml - nothing enforces the description's contents mechanically yet + ### 2026-09-06 - The profile seam is built (ADR-0020) **What changed:** `connect()` reads the unit's `Version` before the handshake,