Contributor Cheat Sheet¶

Everything you need to know on one page. The full docs are linked if you want details.

Setup (once)¶

Fork the repo on GitHub first, then:

git clone https://github.com/<your-username>/ChuMicro.git
cd ChuMicro
git remote add upstream https://github.com/ChuMicro/ChuMicro.git
python scripts/prepare_workspace.py                 # first-time bootstrap
source .venv/bin/activate                           # then activate the venv

Why prepare_workspace.py? It's the only command that runs on a fresh clone with zero third-party packages installed. It auto-detects or creates .venv, installs every library and support package, and runs lint + host tests to confirm the install. After that, your environment is live.

For everyday refreshes (after a git pull that touches dependencies or adds a library) run python scripts/run.py setup. Safe to re-run any time; does the same install/refresh work as the first-time bootstrap, but assumes the venv already exists.

Workflow (every change)¶

git checkout main && git pull upstream main && git push origin main
git checkout -b fix/my-change
# ... make changes ...
python scripts/run.py preflight       # must print "Preflight passed"
git add <changed files> && git commit # imperative subject, explain why
git push -u origin fix/my-change      # then open PR on GitHub

The 10 rules¶

1. Preflight is the one required gate. python scripts/run.py preflight. If it passes, CI will pass.
2. Use descriptive names. The linter names the exact replacement, so each hit is mechanical; expect a few in your first PR. Single-letter for-loop targets (for i in range(10)) are fine. (Decision 0022)
3. No async/await. CircuitPython's asyncio has a broken stream layer and every await allocates there; yield from is one bytecode on both device runtimes. Services are tick-driven (check/handle); sequential flows are generators via runner.add_generator. Lint-enforced. (Decision 0087)
4. Accept dependencies as constructor parameters. Don't import board or busio at the top level. This makes code testable without hardware.
5. Tests live next to the code. libraries/<name>/tests/. Run them with pytest libraries/<name>/tests/.
6. Bump VERSION when you change source code. Edit libraries/<name>/VERSION. CI catches it if you forget.
7. Docstrings are required on public functions. Types go on the signature, descriptions in the docstring.
8. f-strings everywhere. No % formatting, no .format().
9. const() and memoryview are optional on day one. Focus on correctness first, optimize later.
10. Update docs that your change affects. Not 10 files, just the ones directly impacted. Reviewers catch the rest.

Common commands¶

Grouped by what you're trying to do. Preflight is the one command you actually have to remember; everything else is reference.

Every PR¶

Testing¶

Bare pytest from the repo root is the everyday command for iteration: fast, IDE-play-button-friendly. python scripts/run.py test wraps pytest in per-library subprocesses that enforce the coverage gates (Decision 0009); preflight uses that wrapper, so you usually don't need to invoke it directly.

Cross-runtime testing¶

Device testing¶

Both pytest libraries/<name>/functional_tests/ and python scripts/run.py test-libraries-functional go through the same chumicro-pytest-device plugin: the bare-pytest form is what IDE play buttons use, the runner form is the commit-gating wrapper. See device-testing.md for the --runtime / --deploy-mode flag matrix.

Docs and publishing¶

Where things live¶

When something fails¶

Browsing coverage in detail: After running tests, generate an HTML report with python -m coverage html and open htmlcov/index.html. Covered lines show in green, missed lines in red; much easier than reading line numbers from the terminal. (htmlcov/ is gitignored.)

Links¶

• Full contributing guide
• Style guide
• PR guide
• Device testing
• Troubleshooting
• Design decisions