Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 12 additions & 3 deletions .github/PULL_REQUEST_TEMPLATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,12 +8,21 @@

## Testing

<!-- How did you verify this? If you tested on real hardware, say which CorOS /
Cortex Control version and how you checked (read-back, or watching the unit).
Offline-only is fine for many changes - just say so. -->
<!-- Offline: `python -m pytest -q` and mypy run in CI. Say what else you ran. -->

## Hardware

<!-- Every pull request runs the hardware suite before it is marked ready; see
contributing.md, "Before you mark a pull request ready". Fill in ONE of:
- Run: `pytest tests/hardware --hardware` on commit <short hash>, CorOS <version>.
Paste the `operations on ...` block and pytest's last line. If the change
adds or alters an operation, say how you verified it (read-back, or the screen).
- No unit: say so and mark ready anyway; a maintainer runs the suite before merging.
- Waived by a maintainer, with the reason (a change that cannot reach the wire). -->

## 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
Expand Down
1 change: 1 addition & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
48 changes: 41 additions & 7 deletions contributing.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand All @@ -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

Expand Down
25 changes: 23 additions & 2 deletions docs/STEERING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down Expand Up @@ -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

Expand All @@ -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,
Expand Down
Loading