Files

Bilal f62529ad91 docs: Add lightweight contributor onboarding documentation (#894 )

### Summary

This PR introduces a lightweight contributor onboarding docs section
under `docs/contributing/` and improves local formatting ergonomics for
first-time contributors.

The goal is to make CrossPoint easier to contribute to for software
developers who are new to embedded systems (like me), while keeping
onboarding modular and aligned with existing project docs.

### What changed

- Added contributor docs hub: `docs/contributing/README.md`
- Added focused onboarding pages:
  - `docs/contributing/getting-started.md`
  - `docs/contributing/architecture.md`
  - `docs/contributing/development-workflow.md`
  - `docs/contributing/testing-debugging.md`
- Linked contributor docs from `README.md` for discoverability
- Expanded architecture documentation with Mermaid diagrams
- Improved `bin/clang-format-fix`:
  - prefers `clang-format-21` when available
- validates formatter version and fails fast with a clear message if too
old
  - handles missing positional arg safely
- Updated docs to explain common `clang-format` setup/version issues and
install paths (including fallback steps when `clang-format-21` is
unavailable in default apt sources)

### Why

- There was no dedicated contributor onboarding path; first-time
contributors had to infer workflow from multiple files.
- New contributors (especially from non-embedded backgrounds) need a
clear mental model of architecture, runtime flow, and debugging process.
- Local formatting setup caused avoidable friction due to clang-format
version mismatch (`.clang-format` expects newer keys used in CI).
- The updates make contribution setup more predictable, reduce
onboarding confusion, and align local checks with CI expectations.

### Additional context

- No firmware behavior/runtime logic was changed; this PR focuses on
contributor experience and tooling clarity.

---

### AI Usage

> Did you use AI tools to help write this code?

Yes, I used AI tools to assist with generating the documentation. I then
manually reviewed, tested, and refined the code to ensure it works
correctly. please feel free to point out any discrepancies or areas for
improvement.

2026-02-22 16:50:08 +11:00

1.3 KiB

Raw Permalink Blame History

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
Branch from master
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

CI enforces formatting, static analysis, and build checks. Use clang-format 21+ locally to match CI. If clang-format is missing or too old locally, see Getting Started.

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.

1.3 KiB Raw Permalink Blame History