mirror of https://github.com/agessaman/meshcore-bot.git synced 2026-08-14 06:29:47 +00:00

Files

T

agessaman ad7df3438b docs: add contributor and security policy, templates, and dependabot

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.

2026-08-07 13:44:55 -07:00

3.7 KiB

Raw Permalink Blame History

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 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.

Development setup

Requires Python 3.10 or newer.

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:

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 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.
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 for private reporting.

License

Contributions are accepted under the MIT License (see LICENSE).

3.7 KiB Raw Permalink Blame History Unescape Escape