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.5 KiB

Raw Permalink Blame History

Getting Started

This guide helps you build and run CrossPoint locally.

Prerequisites

PlatformIO Core (pio) or VS Code + PlatformIO IDE
Python 3.8+
clang-format 21+ in your PATH (CI uses clang-format 21)
USB-C cable
Xteink X4 device for hardware testing

If ./bin/clang-format-fix fails with either of these errors, install clang-format 21:

clang-format: No such file or directory
.clang-format: error: unknown key 'AlignFunctionDeclarations'

Examples:

# Debian/Ubuntu (try this first)
sudo apt-get update && sudo apt-get install -y clang-format-21

# If the package is unavailable, add LLVM apt repo and retry
wget https://apt.llvm.org/llvm.sh
chmod +x llvm.sh
sudo ./llvm.sh 21
sudo apt-get update
sudo apt-get install -y clang-format-21

# macOS (Homebrew)
brew install clang-format

Then verify:

clang-format-21 --version

The reported major version must be 21 or newer.

Clone and initialize

git clone --recursive https://github.com/crosspoint-reader/crosspoint-reader
cd crosspoint-reader

If you already cloned without submodules:

git submodule update --init --recursive

Build

pio run

Flash

pio run --target upload

First checks before opening a PR

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

1.5 KiB Raw Permalink Blame History