|
| 1 | +# Contributing |
| 2 | + |
| 3 | +Thanks for considering a contribution. This is boot-critical firmware — a |
| 4 | +broken bootloader can leave a device needing a hardware programmer to |
| 5 | +recover — so a few things here are stricter than a typical repo. |
| 6 | + |
| 7 | +## Before you start |
| 8 | + |
| 9 | +- **Read [`AGENTS.md`](./AGENTS.md) first.** It covers the board abstraction, |
| 10 | + the build system split (`make` vs. the incomplete `CMakeLists.txt`), the |
| 11 | + vendored submodules, and a list of known gotchas. This file covers |
| 12 | + process; that one covers the code. |
| 13 | +- **New board support needs real hardware.** `UF2_BOARD_ID`, VID/PID, and |
| 14 | + pin definitions cannot be guessed from a datasheet alone — see |
| 15 | + [Adding a new board](#adding-a-new-board) below. |
| 16 | +- **This repo is [MIT-licensed](./LICENSE)** (originally Adafruit |
| 17 | + Industries). By contributing, you agree your changes are under the same |
| 18 | + license. |
| 19 | + |
| 20 | +## Building locally |
| 21 | + |
| 22 | +You need `arm-none-eabi-gcc` and Python 3 installed. |
| 23 | + |
| 24 | +```sh |
| 25 | +git submodule update --init --recursive # lib/nrfx, lib/tinyusb, lib/uf2 — required, not vendored inline |
| 26 | + |
| 27 | +python3 -m venv .venv && source .venv/bin/activate |
| 28 | +pip install adafruit-nrfutil uritemplate requests intelhex setuptools |
| 29 | + |
| 30 | +# ARM GCC 12.3.Rel1 is what CI pins (.github/workflows/githubci.yml). |
| 31 | +# Newer versions (13.x verified working, 15.x does not) can hit a |
| 32 | +# -Werror=array-bounds false positive in bootloader_settings.c — see |
| 33 | +# AGENTS.md's Gotchas section before reaching for a newer toolchain. |
| 34 | + |
| 35 | +make BOARD=wiscore_rak4631_board all |
| 36 | +make BOARD=wiscore_rak4631_board copy-artifact # writes _bin/<board>/ |
| 37 | +``` |
| 38 | + |
| 39 | +Board names are the directory names under `src/boards/`. `tools/build_all.py` |
| 40 | +builds every board and prints a pass/fail + size table — run it before |
| 41 | +opening a PR; it's the same check CI's board matrix does per-PR, just local. |
| 42 | + |
| 43 | +**Use `make`, not `cmake`.** `CMakeLists.txt` only has a `board.cmake` for 2 |
| 44 | +of the 14 boards; `cmake -DBOARD=<anything else>` fails outright. Nobody |
| 45 | +uses the CMake path in practice. |
| 46 | + |
| 47 | +There is no lint or test suite — for a bootloader, "does it compile for |
| 48 | +every board" (CI's job) and real hardware testing are the correctness |
| 49 | +signals that exist. |
| 50 | + |
| 51 | +## Adding a new board |
| 52 | + |
| 53 | +The [README's board list](./README.md#boards-supported) says to raise an |
| 54 | +issue for a board you'd like supported — that's still the right first step, |
| 55 | +and [#4](https://github.com/meshtastic/Adafruit_nRF52_Bootloader_OTAFIX/issues/4) |
| 56 | +and |
| 57 | +[#5](https://github.com/meshtastic/Adafruit_nRF52_Bootloader_OTAFIX/issues/5) |
| 58 | +are open examples. To actually submit the board yourself: |
| 59 | + |
| 60 | +1. You need the physical hardware to test on — a bootloader that compiles |
| 61 | + but was never flashed is not a contribution, it's a liability. |
| 62 | +2. Add `src/boards/<your-board>/board.h` and `board.mk`, following an |
| 63 | + existing board (e.g. `src/boards/wiscore_rak4631_board`) as a template. |
| 64 | +3. `UF2_BOARD_ID` must follow the format in the |
| 65 | + [UF2 spec](https://github.com/microsoft/uf2#files-exposed-by-bootloaders). |
| 66 | + If your board has an allocated VID/PID, link to it in the PR. |
| 67 | +4. Confirm `make BOARD=<your-board> all` succeeds and the resulting UF2 |
| 68 | + actually boots the board correctly — not just compiles. |
| 69 | +5. The PR template has a checklist for exactly this; fill it in. |
| 70 | + |
| 71 | +## Pull requests |
| 72 | + |
| 73 | +- CI (`.github/workflows/githubci.yml`) builds every board in the matrix on |
| 74 | + every PR. Branch protection on `master` requires all of those checks to |
| 75 | + pass before merge. |
| 76 | +- Recent commit history is |
| 77 | + [Conventional Commits](https://www.conventionalcommits.org/)-style |
| 78 | + (`docs:`, `ci:`, `chore:`, etc.); older history (pre-fork) is looser — |
| 79 | + match the newer style going forward. |
| 80 | +- Keep PRs scoped to one change. A board addition, a docs fix, and a CI |
| 81 | + tweak are three PRs, not one. |
| 82 | + |
| 83 | +## Code of Conduct and security |
| 84 | + |
| 85 | +This project follows the |
| 86 | +[Meshtastic Code of Conduct](./CODE_OF_CONDUCT.md). Report security |
| 87 | +vulnerabilities privately per [`SECURITY.md`](./SECURITY.md) — not as a |
| 88 | +public issue. |
0 commit comments