docs: Add lightweight contributor onboarding documentation#894
Merged
daveallie merged 8 commits intocrosspoint-reader:masterfrom Feb 22, 2026
Merged
docs: Add lightweight contributor onboarding documentation#894daveallie merged 8 commits intocrosspoint-reader:masterfrom
daveallie merged 8 commits intocrosspoint-reader:masterfrom
Conversation
bilalix
changed the title
bilalix
changed the title
Contributor
|
Related discussions at #890 |
Contributor
📝 WalkthroughWalkthroughAdds a new contributor documentation set (getting started, architecture, workflow, testing), minor README and .gitignore edits, and updates Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes 🚥 Pre-merge checks | ✅ 2✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Fix all issues with AI agents
Verify each finding against the current code and only fix it if needed.
In `@bin/clang-format-fix`:
- Around line 17-35: The preflight guard mistakenly only checks for
"clang-format" and will exit early in environments that have only
"clang-format-21"; update the initial binary-detection block so it accepts
either binary and sets CLANG_FORMAT_BIN accordingly (i.e., check for
clang-format-21 first, then clang-format, or test both in one conditional) so
the subsequent CLANG_FORMAT_VERSION_RAW and CLANG_FORMAT_MAJOR logic can run;
modify the existing if/elif/else that sets CLANG_FORMAT_BIN to include
"clang-format-21" as a valid hit and only exit with the error message if neither
binary is found.
In `@docs/contributing/architecture.md`:
- Around line 124-125: Change the phrase "layout related settings" to the
hyphenated compound adjective "layout-related settings" so the line that
currently reads 'rendering favors reusing precomputed layout data to keep page
turns responsive on constrained hardware' uses the corrected compound modifier
by replacing the unhyphenated instance "layout related settings" with
"layout-related settings".
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (8)
.gitignoreREADME.mdbin/clang-format-fixdocs/contributing/README.mddocs/contributing/architecture.mddocs/contributing/development-workflow.mddocs/contributing/getting-started.mddocs/contributing/testing-debugging.md
🧰 Additional context used
🪛 LanguageTool
docs/contributing/architecture.md
[grammar] ~124-~124: Use a hyphen to join words.
Context: ...sting parameters such as font and layout related settings - rendering favors reus...
(QB_NEW_EN_HYPHEN)
[style] ~191-~191: To elevate your writing, try using an alternative expression here.
Context: ...hing choices - main loop responsiveness matters for input, power handling, and watchdog...
(MATTERS_RELEVANT)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: cppcheck
- GitHub Check: build
🔇 Additional comments (6)
.gitignore (1)
13-13: LGTM — .venv ignore is helpful.Keeps local Python virtual environments out of version control.
README.md (1)
155-158: Nice addition — improves contributor discoverability.Clear entry point for new contributors.
docs/contributing/development-workflow.md (1)
1-43: Solid, concise workflow guidance.Clear steps and good cross-links for contributors.
docs/contributing/README.md (1)
1-11: LGTM — clear contributor hub.Navigation links are straightforward.
docs/contributing/testing-debugging.md (1)
1-48: LGTM — useful testing/debugging checklist.Nice separation of local checks, flashing, and bug report guidance.
docs/contributing/getting-started.md (1)
1-80: LGTM — comprehensive and easy to follow.Great end-to-end onboarding flow for first-time contributors.
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
bin/clang-format-fix (1)
40-44: Consider null-delimited pipeline for filenames with spaces.The current pipeline splits on newlines/whitespace, which could break on filenames containing spaces. While unlikely in C/C++ projects, using
-zand-0would make this more robust.♻️ Proposed refactor for null-delimited safety
-git ls-files --exclude-standard ${GIT_LS_FILES_FLAGS} \ +git ls-files -z --exclude-standard ${GIT_LS_FILES_FLAGS} \ + | grep -zE '\.(c|cpp|h|hpp)$' \ + | grep -zv -E '^lib/EpdFont/builtinFonts/' \ + | grep -zv -E '^lib/Epub/Epub/hyphenation/generated/' \ + | xargs -0 -r "${CLANG_FORMAT_BIN}" -style=file -i - | grep -E '\.(c|cpp|h|hpp)$' \ - | grep -v -E '^lib/EpdFont/builtinFonts/' \ - | grep -v -E '^lib/Epub/Epub/hyphenation/generated/' \ - | xargs -r "${CLANG_FORMAT_BIN}" -style=file -i🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@bin/clang-format-fix` around lines 40 - 44, The pipeline that runs clang-format should be made null-delimited to handle filenames with spaces: change the commands using git ls-files, grep and xargs so git ls-files emits NULs (git ls-files -z), each grep uses -z to operate on NUL-delimited input and the final xargs invocation uses -0 (and keep -r) when invoking "${CLANG_FORMAT_BIN}" -style=file -i; update the sequence that currently references git ls-files, grep -E / grep -v -E and xargs to use -z/-0 respectively so filenames with spaces are preserved.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
bin/clang-format-fixdocs/contributing/architecture.md
🧰 Additional context used
🪛 LanguageTool
docs/contributing/architecture.md
[style] ~191-~191: To elevate your writing, try using an alternative expression here.
Context: ...hing choices - main loop responsiveness matters for input, power handling, and watchdog...
(MATTERS_RELEVANT)
🔇 Additional comments (16)
bin/clang-format-fix (3)
3-12: LGTM!The dual-binary detection logic correctly prefers
clang-format-21and falls back toclang-format, addressing the previous review feedback. The error message provides clear guidance for installation.
16-19: LGTM!The
${1:-}pattern correctly handles the optional argument safely underset -u, and the flag logic is clear.
24-29: LGTM!The version validation logic correctly enforces the minimum version requirement and provides clear, actionable error messages when the check fails.
docs/contributing/architecture.md (13)
1-6: LGTM! Clear introduction.The opening provides a concise overview of the project's purpose, target hardware, and architectural approach.
7-22: LGTM! System diagram is clear.The Mermaid diagram effectively visualizes the system layers from hardware to application components.
24-46: LGTM! Runtime lifecycle is well documented.The flowchart clearly illustrates the boot sequence, main loop, and sleep behavior.
47-63: LGTM! Activity model is well explained.The section clearly describes the Activity pattern and organizes the different activity groups.
64-86: LGTM! Reader pipeline is clear.The flowchart and caching explanation effectively communicate the reader architecture and design rationale.
87-127: LGTM! Detailed call graph with helpful notes.The flowchart provides excellent detail on the EPUB reading path, and the notes explain important caching and persistence considerations.
128-148: LGTM! State management is well documented.The section clearly explains the singleton pattern and persistence strategy with a helpful directory structure example. The reference to
docs/file-formats.mdprovides a useful pointer for implementation details.
150-166: LGTM! Networking architecture is concise.The section effectively summarizes the web server modes and behavior. The reference to the endpoint documentation is helpful.
168-175: LGTM! Important contributor guidance.This section provides essential information about generated files that contributors should not edit manually.
177-186: LGTM! Helpful directory reference.The section provides a useful quick reference for navigating the codebase structure.
187-192: LGTM! Essential design context.This section effectively explains the embedded constraints that inform architectural decisions.
194-199: LGTM! Good contributor guidance.Directing contributors to scope and governance documentation helps maintain project focus.
148-148: No action needed—all referenced documentation files exist.The cross-references to
docs/file-formats.md,docs/webserver-endpoints.md,SCOPE.md, andGOVERNANCE.mdare valid and present in the repository.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@bin/clang-format-fix`:
- Line 14: The strict shell flags set by set -euo pipefail cause the pipeline
that extracts the version (the grep -oE '[0-9]+' pipeline) to abort the script
if grep returns non-zero, skipping the intended graceful error handling; update
the script so the version extraction cannot trigger an immediate exit—either
move the extraction out from under strict mode or temporarily disable
exit-on-failure around the pipeline (e.g., run the grep pipeline with a safe
fallback or append a || true) and then check the result explicitly before
invoking the existing error handling logic referenced around the version
extraction and the graceful error path.
---
Nitpick comments:
In `@bin/clang-format-fix`:
- Around line 40-44: The pipeline that runs clang-format should be made
null-delimited to handle filenames with spaces: change the commands using git
ls-files, grep and xargs so git ls-files emits NULs (git ls-files -z), each grep
uses -z to operate on NUL-delimited input and the final xargs invocation uses -0
(and keep -r) when invoking "${CLANG_FORMAT_BIN}" -style=file -i; update the
sequence that currently references git ls-files, grep -E / grep -v -E and xargs
to use -z/-0 respectively so filenames with spaces are preserved.
| exit 1 | ||
| fi | ||
|
|
||
| set -euo pipefail |
Contributor
There was a problem hiding this comment.
set -euo pipefail may cause silent failure on unusual version strings.
With pipefail enabled, if grep -oE '[0-9]+' on line 22 finds no match (returns non-zero), the script exits immediately before reaching the graceful error handling at line 24. Consider suppressing the pipeline exit status or moving the version extraction before strict mode.
🛠️ Proposed fix to handle grep failure gracefully
-CLANG_FORMAT_MAJOR="$(printf '%s\n' "${CLANG_FORMAT_VERSION_RAW}" | grep -oE '[0-9]+' | head -n1)"
+CLANG_FORMAT_MAJOR="$(printf '%s\n' "${CLANG_FORMAT_VERSION_RAW}" | grep -oE '[0-9]+' | head -n1 || true)"Also applies to: 21-22
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@bin/clang-format-fix` at line 14, The strict shell flags set by set -euo
pipefail cause the pipeline that extracts the version (the grep -oE '[0-9]+'
pipeline) to abort the script if grep returns non-zero, skipping the intended
graceful error handling; update the script so the version extraction cannot
trigger an immediate exit—either move the extraction out from under strict mode
or temporarily disable exit-on-failure around the pipeline (e.g., run the grep
pipeline with a safe fallback or append a || true) and then check the result
explicitly before invoking the existing error handling logic referenced around
the version extraction and the graceful error path.
Contributor
There was a problem hiding this comment.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
README.mdbin/clang-format-fix
🚧 Files skipped from review as they are similar to previous changes (1)
- README.md
🔇 Additional comments (2)
bin/clang-format-fix (2)
3-12: LGTM!The binary selection logic correctly prefers
clang-format-21and falls back toclang-format, addressing the earlier concern about environments with onlyclang-format-21installed. The error message is also clear and helpful.
40-45: LGTM!The formatting pipeline correctly uses
${CLANG_FORMAT_BIN}and the file filtering logic is sound. The exclusions for generated directories are well-documented in the comments above.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In `@bin/clang-format-fix`:
- Around line 21-22: The pipeline assignment to CLANG_FORMAT_MAJOR can fail
under set -euo pipefail if grep finds no digits; modify the command that
computes CLANG_FORMAT_MAJOR (currently using CLANG_FORMAT_VERSION_RAW and grep
-oE '[0-9]+') to tolerate no-match by appending a fallback (e.g., make the grep
step non-fatal with "|| true" or use a safe extraction method) so the script
does not exit early, then explicitly check CLANG_FORMAT_MAJOR for emptiness and
emit the existing helpful error message if it is unset; update the code around
CLANG_FORMAT_VERSION_RAW and CLANG_FORMAT_MAJOR to implement this non-fatal grep
and the subsequent empty-value check.
daveallie
approved these changes
Feb 22, 2026
lukestein
pushed a commit
to lukestein/crosspoint-reader
that referenced
this pull request
Feb 22, 2026
…t-reader#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.
lukestein
pushed a commit
to lukestein/crosspoint-reader
that referenced
this pull request
Feb 22, 2026
…t-reader#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.
lukestein
pushed a commit
to lukestein/crosspoint-reader
that referenced
this pull request
Feb 22, 2026
…t-reader#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.
lukestein
pushed a commit
to lukestein/crosspoint-reader
that referenced
this pull request
Feb 22, 2026
…t-reader#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.
lukestein
pushed a commit
to lukestein/crosspoint-reader
that referenced
this pull request
Feb 22, 2026
…t-reader#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.
lukestein
pushed a commit
to lukestein/crosspoint-reader
that referenced
this pull request
Feb 22, 2026
…t-reader#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.
lukestein
pushed a commit
to lukestein/crosspoint-reader
that referenced
this pull request
Feb 22, 2026
…t-reader#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.
lukestein
pushed a commit
to lukestein/crosspoint-reader
that referenced
this pull request
Feb 22, 2026
…t-reader#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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
docs/contributing/README.mddocs/contributing/getting-started.mddocs/contributing/architecture.mddocs/contributing/development-workflow.mddocs/contributing/testing-debugging.mdREADME.mdfor discoverabilitybin/clang-format-fix:clang-format-21when availableclang-formatsetup/version issues and install paths (including fallback steps whenclang-format-21is unavailable in default apt sources)Why
.clang-formatexpects newer keys used in CI).Additional context
AI Usage
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.