mirror of
https://github.com/agessaman/meshcore-bot.git
synced 2026-08-27 21:10:13 +00:00
agessaman
ad7df3438b
CONTRIBUTING covers dev setup, reproducing all six CI jobs locally, and the house rules a newcomer would otherwise trip over: append-only migrations, config changes needing config.ini.example updates, new docs pages needing an mkdocs nav entry, the ruff pin, and PRs targeting dev. SECURITY routes reports through GitHub private vulnerability reporting rather than an email address, with a 10-day acknowledgement and 30-day assessment window. Scope names what this codebase actually exposes, and explicitly puts the MeshCore protocol, RF-layer attacks, and running the viewer without a password out of scope. Issue forms collect the details every radio bug report needs — version, transport, hardware, install method — and the feature form asks up front whether a proposal spends mesh airtime. Blank issues stay enabled since Discussions is not turned on, so they are the only route for questions. Dependabot covers GitHub Actions weekly, where a stale or compromised action is a real supply-chain risk. pip and npm are grouped and monthly: runtime deps are >= ranges, so version updates are mostly floor bumps, and security fixes arrive through Dependabot alerts regardless.
104 lines
3.7 KiB
Markdown
104 lines
3.7 KiB
Markdown
# Contributing to MeshCore Bot
|
||
|
||
Thanks for your interest. This project runs on real radios on real meshes, so
|
||
the bar for changes is partly technical and partly about being a good mesh
|
||
citizen — see [Airtime matters](#airtime-matters) below.
|
||
|
||
## Before you start
|
||
|
||
For anything larger than a bug fix, open an issue first. It is cheaper to agree
|
||
on an approach than to rework a finished pull request.
|
||
|
||
If your change is specific to your own deployment — a custom command, a private
|
||
service integration — it probably belongs in `local/` rather than upstream. See
|
||
[docs/local-plugins.md](docs/local-plugins.md).
|
||
|
||
## Development setup
|
||
|
||
Requires Python 3.10 or newer.
|
||
|
||
```bash
|
||
git clone https://github.com/agessaman/meshcore-bot
|
||
cd meshcore-bot
|
||
make dev # creates .venv, installs runtime + test + lint dependencies
|
||
```
|
||
|
||
## Running the checks
|
||
|
||
CI runs six jobs. You can reproduce all of them locally, and doing so before
|
||
pushing saves a round trip:
|
||
|
||
```bash
|
||
make test # pytest (CI matrix: 3.10–3.13)
|
||
make lint # ruff check + mypy
|
||
python scripts/check_log_injection.py # no new unsanitized logger calls
|
||
npm ci && npm run lint:frontend # HTMLHint + ESLint on templates
|
||
shellcheck --severity=warning **/*.sh # shell scripts
|
||
```
|
||
|
||
`make fix` auto-fixes most ruff findings.
|
||
|
||
Ruff is pinned to `0.15.15` in `pyproject.toml` (`required-version`). An
|
||
unpinned `pip install ruff` will disagree with CI — use `make dev`.
|
||
|
||
## House rules
|
||
|
||
### Airtime matters
|
||
|
||
Every command costs shared, unlicensed spectrum that the whole mesh depends on.
|
||
New commands should justify their airtime: prefer terse replies, respect
|
||
`max_response_hops`, and default anything chatty to off. Features that spend
|
||
airtime on a schedule need a conservative default interval.
|
||
|
||
### Database migrations are append-only
|
||
|
||
Add a new numbered migration; never edit or remove an existing one. See
|
||
**Database Migration** under
|
||
[Adding New Plugins](README.md#adding-new-plugins) in the README, which also
|
||
covers adding commands and service plugins.
|
||
|
||
### Config changes travel with their examples
|
||
|
||
CI validates every shipped config against the schema with
|
||
`validate_config.py --strict`. A new setting needs an entry in
|
||
`config.ini.example` and, where relevant, in the minimal and quickstart
|
||
templates.
|
||
|
||
### Docs changes travel with their nav entry
|
||
|
||
New pages under `docs/` must be added to `nav:` in `mkdocs.yml`, or they will
|
||
not appear on the documentation site.
|
||
|
||
### Logging is sanitized
|
||
|
||
User-controlled values must not flow unescaped into log calls.
|
||
`scripts/check_log_injection.py` enforces this against a baseline.
|
||
|
||
## Pull requests
|
||
|
||
- Branch from `dev` and target `dev` — not `main`.
|
||
- Commit messages follow Conventional Commits: `feat(scope):`, `fix(scope):`,
|
||
`docs:`, `perf(scope):`, `build(scope):`.
|
||
- Add tests for behavior changes.
|
||
- Add a `CHANGELOG.md` entry for anything user-visible, under an
|
||
`## [Unreleased]` heading at the top of the file — create that heading if the
|
||
previous release has just been tagged and it is not there. The format follows
|
||
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
|
||
- Note any hardware you tested against — board, transport, and firmware version.
|
||
Much of this code can only be exercised properly on a device.
|
||
|
||
## Reporting bugs
|
||
|
||
Open an issue including the bot version (`git describe --tags`), the relevant
|
||
`config.ini` section with keys and tokens redacted, and log output from around
|
||
the time of the failure.
|
||
|
||
## Security
|
||
|
||
Please do not report security issues in a public issue — see
|
||
[SECURITY.md](SECURITY.md) for private reporting.
|
||
|
||
## License
|
||
|
||
Contributions are accepted under the MIT License (see [LICENSE](LICENSE)).
|