Sample data collection

.gitattributes

@@ -0,0 +1,18 @@
+# Line-ending policy: LF everywhere, on every platform.
+# Identical working trees on Windows and Linux mean one patch/diff flavor
+# and byte-identical checkouts; modern Windows tooling is LF-clean.
+* text=auto eol=lf
+
+# Binary payloads: never normalize.
+*.iq  binary
+*.wav binary
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.bin binary
+
+# Frozen verbatim fixtures are byte-exact by definition: real tool output
+# captured for parser tests. Normalizing their line endings would silently
+# alter the very bytes they exist to preserve.
+hackrfpy/tests/fixtures/** -text

.github/workflows/tests.yml

@@ -26,6 +26,13 @@ jobs:
       matrix:
         # windows-latest is first because it is the platform this library
         # targets; the cross-platform lifecycle stubs must pass there.
+        # ubuntu re-entered the matrix 2026-09-19: Linux was verified
+        # against a real board (Debian 12, full suite incl. hardware tests,
+        # 227/227) and is held to the same standards as Windows. This also
+        # puts the Linux pdeathsig dead-man path back under regression
+        # testing. The verification itself surfaced and fixed two lifecycle
+        # bugs (frozen-writer USB-claim leak; open-retry race) -- see the
+        # CHANGELOG.
         os: [windows-latest, ubuntu-latest, macos-latest]
         python-version: ["3.11", "3.12", "3.13"]
 
@@ -42,12 +49,12 @@ jobs:
         run: uv sync
 
       - name: Run test suite (hardware tests deselected)
-        run: uv run pytest -m "not hardware" --cov=hackrfpy --cov-report=xml --cov-report=term-missing
+        run: uv run pytest -m "not hardware" --cov=hackrfpy --cov-report=xml --cov-report=term-missing --cov-fail-under=85
 
       - name: Upload coverage to Codecov
         # Optional: only runs once linked at https://codecov.io. Tokenless for
         # public repos. Safe to leave in before linking - it just no-ops/soft-fails.
-        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
+        if: matrix.os == 'windows-latest' && matrix.python-version == '3.12'
         uses: codecov/codecov-action@v5
         with:
           files: hackrfpy/coverage.xml

.gitignore

@@ -216,3 +216,4 @@ __marimo__/
 
 # Streamlit
 .streamlit/secrets.toml
+hackrfpy/tests/fm_testdata/

CONTRIBUTING.md

@@ -17,7 +17,10 @@ path.
   or code that reproduces it.
 - **Request a feature** — open an issue with the feature template. Note that
   signal processing (demod, FFT, waterfalls) is intentionally **out of scope**
-  for this repo; see `project_summary.md`.
+  for the library API — this project is transport + control. The `examples/`
+  directory may demonstrate downstream processing (`fm_demod_to_wav.py`) to
+  show where the boundary sits, but the API stays at `complex64` in, files
+  out.
 - **Improve docs** — README fixes, clearer examples, and beginner notes are all
   welcome and don't require hardware.
 - **Submit code** — see the workflow below.
@@ -44,12 +47,25 @@ Run these from the `hackrfpy/` directory:
 uv run pytest -m "not hardware"     # full hardware-free suite must pass
 uv run ruff check .                 # lint
 uv run ruff format .                # apply formatting
-uv run mypy src/hackrfpy            # type check (advisory for now)
+uv run mypy src/hackrfpy            # type check (BLOCKING in CI)
 ```
 
-CI runs the same suite across Windows, Linux, and macOS on Python 3.11–3.13.
-Windows is the primary target platform, so process-lifecycle changes must pass
-there specifically.
+Also expected with a code PR:
+
+- **A CHANGELOG entry** under `[Unreleased]` — this project's changelog is
+  detailed and rationale-bearing; say what changed and why.
+- **Docstrings on new public API** — `tests/test_docstrings.py` gates the
+  whole public surface and will fail your PR without them.
+- **Coverage** — CI gates at 85% (see the policy at the bottom of this file);
+  new code arrives with its tests.
+- **Hardware evidence for core changes** — any change under `src/hackrfpy/`
+  requires a full-suite run on Windows with a real HackRF attached (hardware
+  tests passing), reported in the PR. See the policy below.
+
+CI runs the suite on Windows and macOS across Python 3.11–3.13. Windows is
+the primary — and only hardware-verified — platform, so process-lifecycle
+changes must pass there specifically. Linux is not in the CI matrix: see the
+platform standard in the coverage policy below.
 
 ## Adding a command
 
@@ -75,20 +91,49 @@ tests import. Don't hard-code envelope numbers in a method.
 ## Tests that touch hardware
 
 Tests that need a real board are marked `@pytest.mark.hardware` and self-skip
-when no device is detected. Parser fixtures live in `tests/fixtures/` and are
-frozen from real hardware output via `tests/collect_real_data.py`. If you add a
-parser, add a real-output fixture rather than a hand-written one where possible.
+when no device is detected. A second, lighter category is marked with a
+`needs_tools` skipif: those need the real `hackrf-tools` binaries on `PATH`
+but **no board**, so they run on any machine with the tools installed — which
+is why passed/skipped counts differ between machines. Parser fixtures live in
+`tests/fixtures/` and are frozen from real hardware output via
+`tests/collect_real_data.py`. If you add a parser, add a real-output fixture
+rather than a hand-written one where possible.
 
 ## Commit and PR conventions
 
 - Keep PRs focused; one logical change per PR is easiest to review.
 - Reference the issue the PR closes (`Closes #123`).
-- Describe what you tested, and whether it was tested against real hardware or
-  stubs only.
-- New public methods need a README entry in the Method Reference and, ideally, a
-  runnable example under `examples/`.
+- Describe what you tested. For changes under `src/hackrfpy/` (the core
+  library), a full-suite run on Windows with a real HackRF attached — hardware
+  tests passing — is **required**, and the PR should say so (paste the pytest
+  tail). Docs, examples, and test-only changes are exempt. CI cannot attach a
+  board, so this is the human half of the quality gate; maintainers may
+  re-verify on their own hardware before merge.
+- New public methods need a README entry in the Method Reference in the main repo README
+  and, ideally, a runnable example under `examples/`.
 
 ## License
 
 By contributing, you agree that your contributions are licensed under the
 project's **GPL-2.0-or-later** license.
+
+## Test coverage and platform policy
+
+CI gates coverage at **85% minimum** (`--cov-fail-under=85`, applied on every
+leg of the CI matrix). Coverage below the gate fails the build; new code
+arrives with the tests that keep it above.
+
+**The CI matrix contains hardware-verified platforms** — currently Windows
+(primary) and Linux (verified 2026-09-19), plus macOS pending verification.
+A platform is included when it is verified against a real HackRF
+board, and is then held to the same standards (the 85% gate and the
+hardware-evidence requirement below).
+
+**Core library changes require a passing hardware test.** CI has no board
+attached, so the stub suite is necessary but not sufficient: any PR that
+changes code under `src/hackrfpy/` must include evidence of a full-suite
+run — hardware tests included and passing — on Windows with a real HackRF
+attached. Paste the pytest tail in the PR description. Changes limited to
+docs, examples, or tests are exempt. The gates that CI *can* enforce
+(coverage, lint, types, docstrings) stay automated; this one is enforced by
+review.