Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
79 lines (63 loc) · 3.8 KB

CONTRIBUTING.md

File metadata and controls

79 lines (63 loc) · 3.8 KB
Raw

Contributing

Thanks for helping out with MeshCore for Tanmatsu. This is a community build, not the official MeshCore app; bug reports and feature ideas go to the issue tracker.

Before your first change, read Blueprint.md (the design rationale and how to program here) and Architecture.md (the enforced rules). If you work with Claude or another AI pair programmer, the same model is written as a handbook in .claude/.

When your change is user visible, add a bullet to the [Unreleased] section of CHANGELOG.md, following the fixed format and entry style in Releases.md.

Build and test

make build  DEVICE=tanmatsu      # idf.py build → build/tanmatsu/application.bin
make upload DEVICE=tanmatsu      # badgelink AppFS upload (keeps the launcher)

cd tests && make test            # host gcc tests; CI runs these before the IDF build

Set up the Tanmatsu ESP-IDF toolchain first (see Build-Deploy.md). Other board targets live in sdkconfigs/.

Before you open a PR

  1. cd tests && make test is green. Host tests link against the shipping translation units, so a crypto, parser, regulatory or packet-codec regression fails here.
  2. tests/lint/check-arch-rules.sh, tests/lint/check-structure.sh and tests/lint/check-test-wiring.sh are green. They enforce the include-direction and file-placement rules from Architecture.md, and that every tests/test_*.c is wired into the Makefile (CI runs them too).
  3. tests/lint/check-cppcheck.sh is green. Static analysis over first-party code (warning/performance/portability). Needs cppcheck; CI runs it too.
  4. make build DEVICE=tanmatsu is green.
  5. clang-format -i on the files you touched (.clang-format is the source of truth).
  6. Behaviour that only shows on the badge is tested on a badge. The host tests and the IDF build cannot prove runtime behaviour on the radio or the display; flash it.

Code rules

These keep the codebase reasoned-about rather than just compiling. Full detail in Architecture.md and CLAUDE.md.

  • Respect the layers. Higher layers include lower, never the reverse. nothing in mc_ui speaks the wire protocol. The component REQUIRES graph (components/mc_proto, components/vendor, main) enforces this at build time, and check-arch-rules.sh covers the in-main layering.
  • components/mc_proto/ is the upstream protocol mirror. Keep it free of ESP-IDF / LVGL / BSP includes (C stdlib and POSIX only) so it stays host-testable. Do not extend a wire-format struct locally; take it upstream first, then re-pin the dependency. When the compiler warns inside the mirror, suppress it at the call site, not by editing the mirror.
  • components/vendor/ is third-party code. Do not refactor it or "fix" its TODOs; most TODO markers in the tree are upstream LodePNG comments.
  • Add a host test for any pure logic you add or change. Modules with no ESP-IDF dependency (the protocol codecs, region limits, the GPS and companion parsers) are unit-tested on the host and gate the merge. Keep that property.
  • Comments explain the non-obvious (a wire quirk, a locking coupling), not the obvious. Every source file carries an SPDX header.

Commit and PR style

  • Commit messages and all repository text are in English.
  • One logical change per commit; explain the why, not just the what.
  • PRs target main. CI must be green. See the PR template under .github/.

License

By contributing you agree your work is released under the project's MIT license (see LICENSE).