Contributing

Contributing

Before changing code

1. Search existing issues, pull requests, and docs for the requirement.
2. Update the owning issue or create one with measurable acceptance criteria.
3. Preserve the user's relevant original request as a blockquote, with secrets redacted and only light grammar correction.
4. Identify whether the work can be proven by automated tests or requires a packaged executable, target OS, UART/USBasp, peripheral, or loaded-hardware observation.

Implementation rules

• Keep one serial owner and route secondary surfaces through shared IPC/dispatch paths.
• Keep physical, virtual, PC-sent, and RF key paths immediate. Do not add a gesture delay to pages/actions that do not use hold or double-click semantics.
• Prefer push events. Do not add repeating snapshot polling when the firmware advertises push support.
• Treat optional peripherals as capabilities; one absent module must not prevent initialization or verification of the others.
• Keep Internet proxy selection in standard environment variables, with loopback and local networks bypassed.
• Do not put secrets in configuration files, URLs, logs, issue bodies, tests, or sample commands.
• Use guarded backup/write/verify/reconnect flows for firmware and EEPROM changes.

Alpha compatibility policy

PCController is still alpha. Successive version builds do not need compatibility readers, migrations, aliases, or preservation logic for prior unpublished alpha layouts. Remove superseded alpha-only paths when they no longer serve the current build.

Compatibility belongs to explicit feature/profile builds when multiple profiles are meant to coexist. Such a profile must declare its layout, limits, feature set, and transfer rules independently. Do not smuggle version-history complexity into the ordinary build under the label of compatibility.

Pull requests

• Keep the PR focused and link its owning issue(s).
• Include tests and exact validation commands.
• State hardware or OS evidence honestly; list unverified gates explicitly.
• Merge a qualifying, passing PR once its acceptance criteria are satisfied.
• Mark incomplete work draft/WIP and explain the blocker or missing proof.
• Do not overwrite unrelated changes in a dirty worktree.

Documentation and status

Update operator docs, API contracts, acceptance checklist, generated backlog inputs, and Wiki links when behavior changes. A status is complete only when GitHub, the canonical local branch, generated docs, and verification evidence agree.

See the repository's documentation index and CI/CD and releases guide.