Development Workflow

This page defines the expected local workflow before opening a pull request.

1) Fork and create a focused branch

Fork the repository to your own GitHub account
Clone your fork locally and add the upstream repository if needed
Enable repo hooks once per clone: git config core.hooksPath .githooks && chmod +x .githooks/pre-commit
Branch from the target base branch for the work, usually main for release-bound changes or development for active development
Keep each PR focused on one fix or feature area

2) Implement with scope in mind

Confirm your idea is in project scope: SCOPE.md
Prefer incremental changes over broad refactors

3) Run local checks

./bin/clang-format-fix
pio check --fail-on-defect low --fail-on-defect medium --fail-on-defect high
pio run -e simulator
pio run -e default

CI enforces formatting, static analysis, and the primary firmware build. Use clang-format 21+ locally to match CI. If clang-format is missing or too old locally, see Getting Started. Run plain pio run before larger PRs to build the release variants (teensy, tiny, xlarge, and no_emoji).

4) Open the PR

Use a semantic title (example: fix: avoid crash when opening malformed epub)
Fill out .github/PULL_REQUEST_TEMPLATE.md
Describe the problem, approach, and any tradeoffs
Include reproduction and verification steps for bug fixes

5) Review etiquette

Be explicit and concise in responses
Keep discussions technical and respectful
Assume good intent and focus on code-level feedback

For community expectations, see GOVERNANCE.md.