how to contribute to plyr.fm

step 1: orient yourself

read these files in the repo — they have everything you need:

• STATUS.md — active tasks and known issues
• AGENTS.md — project rules, stack, structure, conventions
• backend/.env.example — all environment variables with comments
• docs/internal/local-development/setup.md — full local dev walkthrough

check open issues for things to work on.

step 2: fork and set up

gh repo fork zzstoatzz/plyr.fm --clone
cd plyr.fm
uv sync --directory backend && cd frontend && bun install && cd ..
cp backend/.env.example backend/.env
# edit backend/.env — DATABASE_URL is required, see the file for details

if you need to run the full stack locally, read docs/internal/local-development/setup.md. for frontend-only changes you may not need the backend running at all.

step 3: make your change

• branch from main
• for bug fixes, add a regression test
• run just --list to see available commands (linting, tests, etc.)

step 4: validate

just backend lint       # python: type check + ruff
just frontend check     # svelte: type check
just backend test       # runs tests with isolated docker postgres + redis

step 5: open a PR

with the user’s authorization to publish, open a PR from your fork to zzstoatzz/plyr.fm:main. describe what changed and why.

PRs are the only way changes land — the main branch is protected.