Skip to content

docs: overhaul for org best practices and dev/usage separation - #14

Merged
jamesarich merged 2 commits into
masterfrom
docs-overhaul
Aug 19, 2026
Merged

docs: overhaul for org best practices and dev/usage separation#14
jamesarich merged 2 commits into
masterfrom
docs-overhaul

Conversation

@jamesarich

Copy link
Copy Markdown
Collaborator

Summary

Docs pass focused on separating usage (README, for end users flashing a device) from development (CONTRIBUTING.md, for anyone building from source or adding a board) - they'd been mixed together in the README.

  • New CONTRIBUTING.md: build setup (moved out of README), a concrete "adding a new board" process pointing at Add board support: NANO_G2_ULTRA (hwModel 18) #4/Add board support: NOMADSTAR_METEOR_PRO (hwModel 96) #5 as live examples, PR/CI/branch-protection expectations, commit-style guidance.
  • README.md: table of contents, a license badge, a License section, a Getting Help section. Build instructions replaced with a pointer to CONTRIBUTING.md/AGENTS.md.
  • .github/ISSUE_TEMPLATE/config.yml: was pointing bug reporters at the Adafruit support forum - not caught in the earlier MeshCore-stripping pass. Now points at Meshtastic Discussions + meshtastic.org, matching Meshtastic-Android's own template.
  • bug_report.yml: added a Board dropdown - previously the single most important diagnostic fact for a bootloader bug wasn't asked for at all. Dropped "Windows 7."
  • PR template: cross-links CONTRIBUTING.md, asks for tools/build_all.py / real-hardware confirmation on new boards.
  • changelog.md: one-line provenance note distinguishing the OTAFIX-era (Meshtastic) entries from the pre-fork Adafruit history.
  • AGENTS.md: "First read" now lists CONTRIBUTING.md.

Test plan

  • yq eval '.' .github/ISSUE_TEMPLATE/*.yml - both valid
  • Every README TOC anchor checked against its actual header slug
  • No functional/code changes - docs and templates only

- Added CONTRIBUTING.md: build setup (moved out of README - that's a
  contributor concern, not an end-user one), a real "adding a new board"
  process referencing issues #4/#5 as live examples, PR/CI/branch-protection
  expectations, and commit-style guidance.
- README.md: added a table of contents, a license badge alongside the
  build one, a License section, and a Getting Help section - replaced
  the embedded build instructions with a pointer to CONTRIBUTING.md/
  AGENTS.md.
- Fixed .github/ISSUE_TEMPLATE/config.yml pointing bug reporters at the
  Adafruit support forum (100% wrong for this repo now) - points at
  Meshtastic Discussions and meshtastic.org instead, matching
  Meshtastic-Android's own template.
- Modernized bug_report.yml: added a Board dropdown (the single most
  important diagnostic fact for a bootloader bug, previously not asked
  for at all), dropped the "Windows 7" option.
- PR template now cross-links CONTRIBUTING.md and asks for
  tools/build_all.py / hardware-tested confirmation on new boards.
- changelog.md: one-line provenance note distinguishing the OTAFIX-era
  (Meshtastic) entries from the pre-fork Adafruit history below them.
- AGENTS.md: "First read" now lists CONTRIBUTING.md.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@coderabbitai

coderabbitai Bot commented Aug 19, 2026

Copy link
Copy Markdown

Warning

Review limit reached

@jamesarich, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 3 minutes

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits within each organization.

For paid Pro and Pro+ reviews, CodeRabbit uses a developer's included PR review attempts over the past 7 days to set the current hourly allowance. At typical activity levels, the full plan allowance applies. Higher sustained activity can lower the allowance until earlier attempts leave the 7-day window.

Please refer docs for additional details.

Review details
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: b739847d-ae5b-4cbd-808b-b77a9dcd8a54

📥 Commits

Reviewing files that changed from the base of the PR and between 82d979e and ccd63b4.

📒 Files selected for processing (7)
  • .github/ISSUE_TEMPLATE/bug_report.yml
  • .github/ISSUE_TEMPLATE/config.yml
  • .github/PULL_REQUEST_TEMPLATE.md
  • AGENTS.md
  • CONTRIBUTING.md
  • README.md
  • changelog.md

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

The nix develop .#otafix shell is one maintainer's personal dev-workspace
setup, not something a general contributor building this repo has any
reason to know about or use. Removed those lines from CONTRIBUTING.md
and AGENTS.md's Build section; kept the ARM GCC version gotcha (still
true and useful for anyone using any toolchain), dropped the UV_PYTHON
gotcha entirely since it was purely about that workspace's shellHook
implementation and has no bearing outside it.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@jamesarich
jamesarich merged commit e69f9cf into master Aug 19, 2026
16 checks passed
@jamesarich
jamesarich deleted the docs-overhaul branch August 19, 2026 01:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant