# Contributing to Pieria Thanks for being here. Pieria is an open-source art appliance, and it gets better the more people put it on hardware we've never seen. There is **no CLA**. You keep the copyright to everything you write. We use the [Developer Certificate of Origin](#developer-certificate-of-origin) — a one-line sign-off, no forms, no accounts, no lawyers. --- ## Ways to help - **Run it on your panel and tell us what broke.** Odd resolutions, e-ink, unusual TVs, and first-boot problems on fresh cards are the most valuable bug reports we get — most of the hard bugs in this project were only ever visible on genuinely fresh hardware. - **Museum API adapters.** New public-domain sources are welcome. See `scout.py` and the existing adapters for the shape. - **Output surfaces.** Home Assistant, TRMNL/BYOS, MagicMirror, Frame TV — anything that can render an image can be a Pieria display. - **Docs.** If the README or `/help` lied to you, that's a bug worth filing. ## Development setup ```bash git clone https://github.com/pieria-art/Pieria.git cd Pieria python3.11 -m venv .venv .venv/bin/pip install -r requirements.txt -r requirements-dev.txt # hooks: ruff (lint/format) + gitleaks (no secrets in commits) .venv/bin/pre-commit install ``` Run the app: ```bash docker compose up -d --build # http://localhost:8000 ``` Run the tests before you open a PR: ```bash .venv/bin/python -m pytest -q ``` ## House rules - **Schema changes go through Alembic.** The schema has exactly one source of truth (`migrations/`). Do not reintroduce `create_all`. Add a migration. - **Boot is a swarm of independent racers.** Anything that samples state once at startup is a latent bug — prefer re-check-until-satisfied over read-once. - **`static/` and templates are baked into the image.** UI changes need a container rebuild; edits on disk are invisible to a running container. - **Never commit secrets.** The gitleaks hook enforces it. API keys are configured in-app or via environment, never in the repo. - Keep edits surgical. Match the style of the file you're in; `ruff` settles the rest. ## Submitting a change 1. Branch from `main`. 2. Make the change, add tests where there's logic worth pinning down. 3. Run `pytest` and let the hooks run. 4. Open a PR describing **what broke or what's better**, and what hardware you tried it on. --- ## Licensing of contributions Pieria is licensed under the **GNU Affero General Public License v3.0** (see [LICENSE](LICENSE)). By signing off on a contribution, you agree that: 1. Your contribution is licensed under **AGPL-3.0**, the same license as the project; and 2. The maintainer may distribute the project — including your contribution — under the terms of **any other license approved by the [Open Source Initiative](https://opensource.org/licenses)**. Clause 2 exists for one reason: so the project can move to a different **open-source** license if an ecosystem or distribution channel ever requires it, without needing to track down every past contributor for permission. It does **not** permit the project or your contribution to be relicensed under a proprietary or non-open-source license, and it never will — that limit is the point of writing it this way. You keep your copyright, and you keep every right to your own code. The grant above is non-exclusive: use your contribution anywhere else you like, under any terms you like. ### The project name is not covered by the license The AGPL covers the **code**. It does not grant rights to the project **name or logo**. You may fork freely — please just give the fork its own name so nobody gets confused about who supports what. See [TRADEMARK.md](TRADEMARK.md). ### AI-assisted contributions Using an AI assistant is fine — much of this project was written that way. You are still the one signing off, so make sure you have the right to contribute what you're submitting and that you understand and stand behind the code. --- ## Developer Certificate of Origin Add a `Signed-off-by` line to each commit: ```bash git commit -s -m "your message" ``` which appends: ``` Signed-off-by: Your Name ``` Use your real name and a real email address. **This is enforced by CI, not just asked for.** The `DCO` check runs on every pull request and fails the PR if any commit in it is missing a `Signed-off-by` trailer matching that commit's author. If it fails, fix it in place rather than opening a new PR: ```bash # Fix just the last commit: git commit --amend -s --no-edit && git push --force-with-lease # Fix every commit on the branch: git rebase --signoff main && git push --force-with-lease ``` Maintainers sign off too — direct commits to `main` aren't run through the PR check, but `git commit -s` is still the habit, no exceptions. That sign-off certifies the following: ``` Developer Certificate of Origin Version 1.1 Copyright (C) 2004, 2006 The Linux Foundation and its contributors. Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. Developer's Certificate of Origin 1.1 By making a contribution to this project, I certify that: (a) The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or (b) The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or (c) The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it. (d) I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved. ```