f62529ad91
### 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.
46 lines
1.8 KiB
Bash
Executable File
46 lines
1.8 KiB
Bash
Executable File
#!/usr/bin/env bash
|
|
|
|
# Check if clang-format is available and pick the preferred binary.
|
|
if command -v clang-format-21 >/dev/null 2>&1; then
|
|
CLANG_FORMAT_BIN="clang-format-21"
|
|
elif command -v clang-format >/dev/null 2>&1; then
|
|
CLANG_FORMAT_BIN="clang-format"
|
|
else
|
|
printf "'clang-format' not found in current environment\n"
|
|
printf "Install clang-format-21 (recommended), clang, clang-tools, or clang-format depending on your distro/os and tooling requirements\n"
|
|
exit 1
|
|
fi
|
|
|
|
set -euo pipefail
|
|
|
|
GIT_LS_FILES_FLAGS=""
|
|
if [[ "${1:-}" == "-g" ]]; then
|
|
GIT_LS_FILES_FLAGS="--modified"
|
|
fi
|
|
|
|
CLANG_FORMAT_VERSION_RAW="$(${CLANG_FORMAT_BIN} --version)"
|
|
CLANG_FORMAT_MAJOR="$(printf '%s\n' "${CLANG_FORMAT_VERSION_RAW}" | grep -oE '[0-9]+' | head -n1)"
|
|
|
|
if [[ -z "${CLANG_FORMAT_MAJOR}" || "${CLANG_FORMAT_MAJOR}" -lt 21 ]]; then
|
|
echo "Error: ${CLANG_FORMAT_BIN} is too old: ${CLANG_FORMAT_VERSION_RAW}"
|
|
echo "This repository's .clang-format requires clang-format 21 or newer."
|
|
echo "Install clang-format-21 and rerun ./bin/clang-format-fix"
|
|
exit 1
|
|
fi
|
|
|
|
# --- Main Logic ---
|
|
|
|
# Format all files (or only modified files if -g is passed)
|
|
|
|
# Use 'git ls-files' to get a list of all files tracked by git:
|
|
# --modified: files tracked by git that have been modified (staged or unstaged)
|
|
# --exclude-standard: ignores files in .gitignore
|
|
# Additionally exclude files in 'lib/EpdFont/builtinFonts/' as they are script-generated.
|
|
# Also exclude files in 'lib/Epub/Epub/hyphenation/generated/' as they are script-generated.
|
|
git ls-files --exclude-standard ${GIT_LS_FILES_FLAGS} \
|
|
| grep -E '\.(c|cpp|h|hpp)$' \
|
|
| grep -v -E '^lib/EpdFont/builtinFonts/' \
|
|
| grep -v -E '^lib/Epub/Epub/hyphenation/generated/' \
|
|
| grep -v -E '^lib/uzlib/' \
|
|
| xargs -r "${CLANG_FORMAT_BIN}" -style=file -i
|