mirror of
https://github.com/ChuckBuilds/LEDMatrix.git
synced 2026-08-06 11:18:06 +00:00
Claude
4808132436
A second-pass content audit checked the guides' substantive claims against the code (the first pass only fixed mechanical drift). Fixes: - GETTING_STARTED: described booting a prebuilt SD image and seeing default clock/weather plugins — neither exists. Now documents the real install (Pi OS Lite + one-shot installer / first_time_install.sh) and that displays come from the Plugin Store. Duration and ordering instructions moved to the Rotation tab where the controls actually live. - WEB_INTERFACE_GUIDE: three whole tabs were undocumented (Rotation, Backup & Restore, Tools) and the Display tab's Vegas Scroll section was unmentioned. Fonts overrides are per display element (not per plugin); Logs has an Auto-scroll checkbox (not a Pause button); the aspirational keyboard-shortcut list and no-JS claim removed. - TROUBLESHOOTING: the hand-written service-file template (wrong user, wrong ExecStart, dropped the autostart gate) replaced with the real systemd/ units + install scripts; recovery steps no longer copy placeholder units verbatim; WiFi curl endpoint corrected to /api/v3/; cache-clearing advice now targets the real cache locations. - ADVANCED_FEATURES: removed a false claim that CacheManager has no delete(); fixed two example snippets that raise TypeError (BackgroundDataService and get_config_file_mode signatures); fixed cache paths, a 5-minute TTL that is actually 1 hour, and the vegas table now links the complete 26-key reference. - EMULATOR_SETUP_GUIDE: documented run.py flags that don't exist (--plugin/--test-plugins) removed in favor of dev_server.py and check_plugin.py; shipped emulator config values corrected (browser adapter default on :8888, not pygame). - PLUGIN_QUICK_REFERENCE: drag-and-drop reordering is shipped, not 'not yet supported'; discovery-fallback and registry-repo claims corrected. PLUGIN_API_REFERENCE: get_vegas_segment_width returns panels, not pixels. CONTRIBUTING: the repo uses flake8/mypy/bandit pre-commit hooks, not black/ruff, and tests need requirements-test.txt. - SKIN_SYSTEM/DEVELOPER_QUICK_REFERENCE: stale module paths. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SXb4mKcAkVaxkeTb3YnAdr
117 lines
4.2 KiB
Markdown
117 lines
4.2 KiB
Markdown
# Contributing to LEDMatrix
|
|
|
|
Thanks for considering a contribution! LEDMatrix is built with help from
|
|
the community and we welcome bug reports, plugins, documentation
|
|
improvements, and code changes.
|
|
|
|
## Quick links
|
|
|
|
- **Bugs / feature requests**: open an issue using one of the templates
|
|
in [`.github/ISSUE_TEMPLATE/`](.github/ISSUE_TEMPLATE/).
|
|
- **Real-time discussion**: the
|
|
[LEDMatrix Discord](https://discord.gg/uW36dVAtcT).
|
|
- **Plugin development**:
|
|
[`docs/PLUGIN_DEVELOPMENT_GUIDE.md`](docs/PLUGIN_DEVELOPMENT_GUIDE.md)
|
|
and the [`ledmatrix-plugins`](https://github.com/ChuckBuilds/ledmatrix-plugins)
|
|
repository.
|
|
- **Security issues**: see [`SECURITY.md`](SECURITY.md). Please don't
|
|
open public issues for vulnerabilities.
|
|
|
|
## Setting up a development environment
|
|
|
|
1. Clone with submodules:
|
|
```bash
|
|
git clone --recurse-submodules https://github.com/ChuckBuilds/LEDMatrix.git
|
|
cd LEDMatrix
|
|
```
|
|
2. For development without hardware, run the dev preview server:
|
|
```bash
|
|
python3 scripts/dev_server.py
|
|
# then open http://localhost:5001
|
|
```
|
|
See [`docs/DEV_PREVIEW.md`](docs/DEV_PREVIEW.md) for details.
|
|
3. To run the full display in emulator mode:
|
|
```bash
|
|
EMULATOR=true python3 run.py
|
|
```
|
|
4. To target real hardware on a Raspberry Pi, follow the install
|
|
instructions in the root [`README.md`](README.md).
|
|
|
|
## Running the tests
|
|
|
|
```bash
|
|
pip install -r requirements.txt -r requirements-test.txt
|
|
pytest
|
|
```
|
|
|
|
See [`docs/HOW_TO_RUN_TESTS.md`](docs/HOW_TO_RUN_TESTS.md) for details
|
|
on test markers, the per-plugin tests, and the web-interface
|
|
integration tests.
|
|
|
|
## Submitting changes
|
|
|
|
1. **Open an issue first** for non-trivial changes. This avoids
|
|
wasted work on PRs that don't fit the project direction.
|
|
2. **Create a topic branch** off `main`:
|
|
`feat/<short-description>`, `fix/<short-description>`,
|
|
`docs/<short-description>`.
|
|
3. **Keep PRs focused.** One conceptual change per PR. If you find
|
|
adjacent bugs while working, fix them in a separate PR.
|
|
4. **Follow the existing code style.** The pre-commit hooks run
|
|
`flake8` (E9, F63, F7, F82 plus bugbear `B` checks), `mypy` on
|
|
`src/`, `bandit`, and `gitleaks` — install them with
|
|
`pre-commit install` so they run on every commit; HTML/JS in
|
|
`web_interface/` follows the patterns already in `templates/v3/`
|
|
and `static/v3/`.
|
|
5. **Update documentation** alongside code changes. If you add a
|
|
config key, document it in the relevant `*.md` file (or, for
|
|
plugins, in `config_schema.json` so the form is auto-generated).
|
|
6. **Run the tests** locally before opening the PR.
|
|
7. **Use the PR template** — `.github/PULL_REQUEST_TEMPLATE.md` will
|
|
prompt you for what we need.
|
|
|
|
## Commit message convention
|
|
|
|
Conventional Commits is encouraged but not strictly enforced:
|
|
|
|
- `feat: add NHL playoff bracket display`
|
|
- `fix(plugin-loader): handle missing class_name in manifest`
|
|
- `docs: correct web UI port in TROUBLESHOOTING.md`
|
|
- `refactor(cache): consolidate strategy lookup`
|
|
|
|
Keep the subject under 72 characters; put the why in the body.
|
|
|
|
## Contributing a plugin
|
|
|
|
LEDMatrix plugins live in their own repository:
|
|
[`ledmatrix-plugins`](https://github.com/ChuckBuilds/ledmatrix-plugins).
|
|
Plugin contributions go through that repo's
|
|
[`SUBMISSION.md`](https://github.com/ChuckBuilds/ledmatrix-plugins/blob/main/SUBMISSION.md)
|
|
process. The
|
|
[`hello-world` plugin](https://github.com/ChuckBuilds/ledmatrix-plugins/tree/main/plugins/hello-world)
|
|
is the canonical starter template.
|
|
|
|
## Reviewing pull requests
|
|
|
|
Maintainer review is by [@ChuckBuilds](https://github.com/ChuckBuilds).
|
|
Community review is welcome on any open PR — leave constructive
|
|
comments, test on your hardware if applicable, and call out anything
|
|
unclear.
|
|
|
|
## Code of conduct
|
|
|
|
This project follows the [Contributor Covenant](CODE_OF_CONDUCT.md). By
|
|
participating you agree to abide by its terms.
|
|
|
|
## License
|
|
|
|
LEDMatrix is licensed under the [GNU General Public License v3.0 or
|
|
later](LICENSE). By submitting a contribution you agree to license it
|
|
under the same terms (the standard "inbound = outbound" rule that
|
|
GitHub applies by default).
|
|
|
|
LEDMatrix builds on
|
|
[`rpi-rgb-led-matrix`](https://github.com/hzeller/rpi-rgb-led-matrix),
|
|
which is GPL-2.0-or-later. The "or later" clause makes it compatible
|
|
with GPL-3.0 distribution.
|