Add CODE_OF_CONDUCT, SECURITY, PR template; link them from README

Tier 1 organizational files that any open-source project at
LEDMatrix's maturity is expected to have. None of these existed
before. They're additive — no existing content was rewritten.

CODE_OF_CONDUCT.md
- Contributor Covenant 2.1 (the de facto standard for open-source
  projects). Mentions both the Discord and the GitHub Security
  Advisories channel for reporting violations.

SECURITY.md
- Private vulnerability disclosure flow with two channels: GitHub
  Security Advisories (preferred) and Discord DM.
- Documents the project's known security model as intentional
  rather than vulnerabilities: no web UI auth, plugins run
  unsandboxed, display service runs as root for GPIO access,
  config_secrets.json is plaintext. These match the limitations
  already called out in PLUGIN_QUICK_REFERENCE.md and the audit
  flagging from earlier in this PR.
- Out-of-scope section points users at upstream
  (rpi-rgb-led-matrix, third-party plugins) so reports land in the
  right place.

.github/PULL_REQUEST_TEMPLATE.md
- 10-line checklist that prompts for the things that would have
  caught the bugs in this very PR: did you load the changed plugin
  once, did you update docs alongside code, are there any plugin
  compatibility implications.
- Linked from CONTRIBUTING.md for the full flow.

README.md
- Added a License section near the bottom (the README previously
  said nothing about the license despite the project being GPL-3.0).
- Added a Contributing section pointing at CONTRIBUTING.md and
  SECURITY.md.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Chuck
2026-04-07 12:52:48 -04:00
parent 44cd3e8c2f
commit 38773044e9
4 changed files with 309 additions and 0 deletions

62
.github/PULL_REQUEST_TEMPLATE.md vendored Normal file
View File

@@ -0,0 +1,62 @@
# Pull Request
## Summary
<!-- 1-3 sentences describing what this PR does and why. -->
## Type of change
<!-- Check all that apply. -->
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation
- [ ] Refactor (no functional change)
- [ ] Build / CI
- [ ] Plugin work (link to the plugin)
## Related issues
<!-- "Fixes #123" or "Refs #123". Use "Fixes" for bug PRs so the issue
auto-closes when this merges. -->
## Test plan
<!-- How did you test this? Check all that apply. Add details for any
checked box. -->
- [ ] Ran on a real Raspberry Pi with hardware
- [ ] Ran in emulator mode (`EMULATOR=true python3 run.py`)
- [ ] Ran the dev preview server (`scripts/dev_server.py`)
- [ ] Ran the test suite (`pytest`)
- [ ] Manually verified the affected code path in the web UI
- [ ] N/A — documentation-only change
## Documentation
- [ ] I updated `README.md` if user-facing behavior changed
- [ ] I updated the relevant doc in `docs/` if developer behavior changed
- [ ] I added/updated docstrings on new public functions
- [ ] N/A — no docs needed
## Plugin compatibility
<!-- For changes to BasePlugin, the plugin loader, the web UI, or the
config schema. -->
- [ ] No plugin breakage expected
- [ ] Some plugins will need updates — listed below
- [ ] N/A — change doesn't touch the plugin system
## Checklist
- [ ] My commits follow the message convention in `CONTRIBUTING.md`
- [ ] I read `CONTRIBUTING.md` and `CODE_OF_CONDUCT.md`
- [ ] I've not committed any secrets or hardcoded API keys
- [ ] If this adds a new config key, the form in the web UI was
verified (the form is generated from `config_schema.json`)
## Notes for reviewer
<!-- Anything reviewers should know — gotchas, things you weren't
sure about, decisions you'd like a second opinion on. -->

137
CODE_OF_CONDUCT.md Normal file
View File

@@ -0,0 +1,137 @@
# Contributor Covenant Code of Conduct
## Our Pledge
We as members, contributors, and leaders pledge to make participation in our
community a harassment-free experience for everyone, regardless of age, body
size, visible or invisible disability, ethnicity, sex characteristics, gender
identity and expression, level of experience, education, socio-economic status,
nationality, personal appearance, race, religion, or sexual identity
and orientation.
We pledge to act and interact in ways that contribute to an open, welcoming,
diverse, inclusive, and healthy community.
## Our Standards
Examples of behavior that contributes to a positive environment for our
community include:
* Demonstrating empathy and kindness toward other people
* Being respectful of differing opinions, viewpoints, and experiences
* Giving and gracefully accepting constructive feedback
* Accepting responsibility and apologizing to those affected by our mistakes,
and learning from the experience
* Focusing on what is best not just for us as individuals, but for the
overall community
Examples of unacceptable behavior include:
* The use of sexualized language or imagery, and sexual attention or
advances of any kind
* Trolling, insulting or derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or email
address, without their explicit permission
* Other conduct which could reasonably be considered inappropriate in a
professional setting
## Enforcement Responsibilities
Community leaders are responsible for clarifying and enforcing our standards of
acceptable behavior and will take appropriate and fair corrective action in
response to any behavior that they deem inappropriate, threatening, offensive,
or harmful.
Community leaders have the right and responsibility to remove, edit, or reject
comments, commits, code, wiki edits, issues, and other contributions that are
not aligned to this Code of Conduct, and will communicate reasons for moderation
decisions when appropriate.
## Scope
This Code of Conduct applies within all community spaces, and also applies when
an individual is officially representing the community in public spaces.
Examples of representing our community include using an official email address,
posting via an official social media account, or acting as an appointed
representative at an online or offline event.
This includes the LEDMatrix Discord server, GitHub repositories owned by
ChuckBuilds, and any other forums hosted by or affiliated with the project.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported to the community leaders responsible for enforcement on the
[LEDMatrix Discord](https://discord.gg/uW36dVAtcT) (DM a moderator or
ChuckBuilds directly) or by opening a private GitHub Security Advisory if
the issue involves account safety. All complaints will be reviewed and
investigated promptly and fairly.
All community leaders are obligated to respect the privacy and security of the
reporter of any incident.
## Enforcement Guidelines
Community leaders will follow these Community Impact Guidelines in determining
the consequences for any action they deem in violation of this Code of Conduct:
### 1. Correction
**Community Impact**: Use of inappropriate language or other behavior deemed
unprofessional or unwelcome in the community.
**Consequence**: A private, written warning from community leaders, providing
clarity around the nature of the violation and an explanation of why the
behavior was inappropriate. A public apology may be requested.
### 2. Warning
**Community Impact**: A violation through a single incident or series
of actions.
**Consequence**: A warning with consequences for continued behavior. No
interaction with the people involved, including unsolicited interaction with
those enforcing the Code of Conduct, for a specified period of time. This
includes avoiding interactions in community spaces as well as external channels
like social media. Violating these terms may lead to a temporary or
permanent ban.
### 3. Temporary Ban
**Community Impact**: A serious violation of community standards, including
sustained inappropriate behavior.
**Consequence**: A temporary ban from any sort of interaction or public
communication with the community for a specified period of time. No public or
private interaction with the people involved, including unsolicited interaction
with those enforcing the Code of Conduct, is allowed during this period.
Violating these terms may lead to a permanent ban.
### 4. Permanent Ban
**Community Impact**: Demonstrating a pattern of violation of community
standards, including sustained inappropriate behavior, harassment of an
individual, or aggression toward or disparagement of classes of individuals.
**Consequence**: A permanent ban from any sort of public interaction within
the community.
## Attribution
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
version 2.1, available at
[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
Community Impact Guidelines were inspired by
[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
For answers to common questions about this code of conduct, see the FAQ at
[https://www.contributor-covenant.org/faq][FAQ]. Translations are available
at [https://www.contributor-covenant.org/translations][translations].
[homepage]: https://www.contributor-covenant.org
[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
[Mozilla CoC]: https://github.com/mozilla/diversity
[FAQ]: https://www.contributor-covenant.org/faq
[translations]: https://www.contributor-covenant.org/translations

View File

@@ -878,3 +878,27 @@ sudo systemctl enable ledmatrix-web.service
### If you've read this far — thanks! ### If you've read this far — thanks!
-----------------------------------------------------------------------------------
## License
LEDMatrix is licensed under the
[GNU General Public License v3.0 or later](LICENSE).
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.
Plugin contributions in
[`ledmatrix-plugins`](https://github.com/ChuckBuilds/ledmatrix-plugins)
are also GPL-3.0-or-later unless individual plugins specify otherwise.
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, the PR
flow, and how to add a plugin. Bug reports and feature requests go in
the [issue tracker](https://github.com/ChuckBuilds/LEDMatrix/issues).
Security issues should be reported privately per
[SECURITY.md](SECURITY.md).

86
SECURITY.md Normal file
View File

@@ -0,0 +1,86 @@
# Security Policy
## Reporting a vulnerability
If you've found a security issue in LEDMatrix, **please don't open a
public GitHub issue**. Disclose it privately so we can fix it before it's
exploited.
### How to report
Use one of these channels, in order of preference:
1. **GitHub Security Advisories** (preferred). On the LEDMatrix repo,
go to **Security → Advisories → Report a vulnerability**. This
creates a private discussion thread visible only to you and the
maintainer.
- Direct link: <https://github.com/ChuckBuilds/LEDMatrix/security/advisories/new>
2. **Discord DM**. Send a direct message to a moderator on the
[LEDMatrix Discord](https://discord.gg/uW36dVAtcT). Don't post in
public channels.
Please include:
- A description of the issue
- The version / commit hash you're testing against
- Steps to reproduce, ideally a minimal proof of concept
- The impact you can demonstrate
- Any suggested mitigation
### What to expect
- An acknowledgement within a few days (this is a hobby project, not
a 24/7 ops team).
- A discussion of the issue's severity and a plan for the fix.
- Credit in the release notes when the fix ships, unless you'd
prefer to remain anonymous.
- For high-severity issues affecting active deployments, we'll
coordinate disclosure timing with you.
## Scope
In scope for this policy:
- The LEDMatrix display controller, web interface, and plugin loader
in this repository
- The official plugins in
[`ledmatrix-plugins`](https://github.com/ChuckBuilds/ledmatrix-plugins)
- Installation scripts and systemd unit files
Out of scope (please report upstream):
- Vulnerabilities in `rpi-rgb-led-matrix` itself —
report to <https://github.com/hzeller/rpi-rgb-led-matrix>
- Vulnerabilities in Python packages we depend on — report to the
upstream package maintainer
- Issues in third-party plugins not in `ledmatrix-plugins` — report
to that plugin's repository
## Known security model
LEDMatrix is designed for trusted local networks. Several limitations
are intentional rather than vulnerabilities:
- **No web UI authentication.** The web interface assumes the network
it's running on is trusted. Don't expose port 5000 to the internet.
- **Plugins run unsandboxed.** Installed plugins execute in the same
Python process as the display loop with full file-system and
network access. Review plugin code (especially third-party plugins
from arbitrary GitHub URLs) before installing. The Plugin Store
marks community plugins as **Custom** to highlight this.
- **The display service runs as root** for hardware GPIO access. This
is required by `rpi-rgb-led-matrix`.
- **`config_secrets.json` is plaintext.** API keys and tokens are
stored unencrypted on the Pi. Lock down filesystem permissions on
the config directory if this matters for your deployment.
These are documented as known limitations rather than bugs. If you
have ideas for improving them while keeping the project usable on a
Pi, open a discussion — we're interested.
## Supported versions
LEDMatrix is rolling-release on `main`. Security fixes land on `main`
and become available the next time users run **Update Code** from the
web UI's Overview tab (which does a `git pull`). There are no LTS
branches.