audio streaming app
plyr.fm
docs: overhaul contributing page, add contribute skill (#1039)
- fix GitHub vs tangled.org messaging (GitHub is primary, tangled is mirror)
- add "using a coding assistant?" section with copy-pasteable prompt
- document Redis requirement (just dev-services) and Postgres setup
- link to backend/.env.example for env var reference
- link to docs-internal/local-development/setup.md for detailed guide
- remove "never push to main" (branch protection handles this)
- add fork-based workflow instructions
- create skills/contribute/SKILL.md for agent-based contributors
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
authored by
Claude Opus 4.6
and committed by
GitHub
0d834e61
9177bc67
+45
-14
docs/contributing.md
+45
-14
docs/contributing.md
···
2
2
title: "contributing"
3
3
---
4
4
5
-
plyr.fm is open source on [tangled.org](https://tangled.org/zzstoatzz.io/plyr.fm). contributions welcome.
5
+
plyr.fm is open source. development happens on [GitHub](https://github.com/zzstoatzz/plyr.fm) (mirrored to [tangled.org](https://tangled.org/zzstoatzz.io/plyr.fm)). contributions welcome — fork the repo and open a PR.
6
+
7
+
## using a coding assistant?
8
+
9
+
if you're using Claude Code, Cursor, Codex, or similar — copy the prompt below into your assistant to get oriented:
10
+
11
+
```
12
+
i want to contribute to plyr.fm. the repo is at https://github.com/zzstoatzz/plyr.fm
13
+
14
+
read the CLAUDE.md at the repo root for project context, then read STATUS.md
15
+
for active tasks. fork the repo, make your change on a branch, run linting
16
+
(just backend lint / just frontend check), add tests for bug fixes, and open a PR.
17
+
18
+
the stack is FastAPI + SvelteKit + Postgres + Redis. use `uv` for Python, `bun`
19
+
for frontend, and `just` as the task runner. see backend/.env.example for all
20
+
environment variables.
21
+
```
22
+
23
+
or install the [contribute skill](https://github.com/zzstoatzz/plyr.fm/tree/main/skills/contribute) for richer agent context.
6
24
7
25
## prerequisites
8
26
9
27
- [uv](https://docs.astral.sh/uv/) (Python 3.11+)
10
28
- [bun](https://bun.sh/) (frontend)
11
29
- [just](https://just.systems/) (task runner)
30
+
- [docker](https://www.docker.com/) (for Redis and test databases)
12
31
13
32
## quickstart
14
33
15
34
```bash
16
-
gh repo clone zzstoatzz/plyr.fm
35
+
# fork on github, then clone your fork
36
+
gh repo fork zzstoatzz/plyr.fm --clone
17
37
cd plyr.fm
18
38
39
+
# install dependencies
19
40
uv sync
20
41
cd frontend && bun install && cd ..
21
42
22
-
cp .env.example .env
23
-
# edit .env with your credentials
43
+
# configure environment
44
+
cp backend/.env.example backend/.env
45
+
# edit backend/.env — see the setup guide linked below for details
46
+
```
47
+
48
+
### running the stack
24
49
25
-
# terminal 1
50
+
```bash
51
+
# start redis (required for background tasks)
52
+
just dev-services
53
+
54
+
# terminal 1 — backend (port 8001, hot reloads)
26
55
just backend run
27
56
28
-
# terminal 2
57
+
# terminal 2 — frontend (port 5173, hot reloads)
29
58
just frontend run
30
59
```
31
60
32
-
visit http://localhost:5173 to see the app.
61
+
the backend needs a Postgres connection. you can use the [Neon](https://neon.tech) dev instance or a local Postgres — set `DATABASE_URL` in your `.env`. see [`backend/.env.example`](https://github.com/zzstoatzz/plyr.fm/blob/main/backend/.env.example) for all configuration options and the [local development setup guide](https://github.com/zzstoatzz/plyr.fm/blob/main/docs-internal/local-development/setup.md) for detailed walkthrough.
33
62
34
63
## workflow
35
64
36
65
1. check [`STATUS.md`](https://github.com/zzstoatzz/plyr.fm/blob/main/STATUS.md) for active tasks
37
66
2. [open an issue](https://github.com/zzstoatzz/plyr.fm/issues) describing the change
38
-
3. branch from `main`, make your changes
39
-
4. open a PR — never push directly to main
67
+
3. fork the repo, branch from `main`, make your changes
68
+
4. open a PR from your fork
40
69
41
70
## useful commands
42
71
43
72
```bash
44
73
just backend run # start backend
45
74
just frontend run # start frontend
46
-
just backend test # run tests (from repo root)
47
-
just backend lint # lint python (ruff)
48
-
just frontend check # lint svelte
49
-
just backend migrate-up # apply migrations
75
+
just dev-services # start redis
76
+
just backend test # run tests (spins up isolated postgres + redis)
77
+
just backend lint # type check + ruff
78
+
just frontend check # svelte type check
79
+
just backend migrate-up # apply database migrations
50
80
```
51
81
52
82
## conventions
···
56
86
- **lowercase aesthetic** in naming, docs, and commits
57
87
- SvelteKit with **Svelte 5 Runes** (`$state`, `$derived`, `$effect`)
58
88
- use `uv` for Python (never `pip`)
89
+
- add regression tests when fixing bugs
59
90
60
-
detailed internal documentation (environment setup, deployment, architecture) is available to active contributors in the `docs-internal/` directory.
91
+
detailed internal documentation (environment setup, deployment, architecture) is in [`docs-internal/`](https://github.com/zzstoatzz/plyr.fm/tree/main/docs-internal).
+100
skills/contribute/SKILL.md
+100
skills/contribute/SKILL.md
···
1
+
---
2
+
name: contribute
3
+
description: Contributing to plyr.fm — an audio streaming app built on ATProto. Use when making changes to the plyr.fm codebase, fixing bugs, adding features, or opening pull requests.
4
+
metadata:
5
+
author: zzstoatzz
6
+
repo: https://github.com/zzstoatzz/plyr.fm
7
+
---
8
+
9
+
# contributing to plyr.fm
10
+
11
+
## orientation
12
+
13
+
1. read `CLAUDE.md` at the repo root — it has project structure, stack details, and rules
14
+
2. read `STATUS.md` for active tasks and known issues
15
+
3. check [open issues](https://github.com/zzstoatzz/plyr.fm/issues) for things to work on
16
+
17
+
## stack
18
+
19
+
- **backend**: FastAPI, SQLAlchemy, Neon Postgres, Cloudflare R2 — in `backend/`
20
+
- **frontend**: SvelteKit (Svelte 5 Runes), Bun — in `frontend/`
21
+
- **task runner**: `just` (justfiles at root, `backend/`, `frontend/`, etc.)
22
+
- **python**: always use `uv`, never `pip`
23
+
- **services**: Redis (via `just dev-services`), transcoder (Rust), moderation (Rust)
24
+
25
+
## making changes
26
+
27
+
1. fork `zzstoatzz/plyr.fm` on GitHub
28
+
2. branch from `main`
29
+
3. make your changes
30
+
4. run linting before committing:
31
+
- `just backend lint` — python type checking + ruff
32
+
- `just frontend check` — svelte type check
33
+
5. add regression tests for bug fixes (`just backend test` runs them)
34
+
6. open a PR from your fork — describe what changed and why
35
+
36
+
## key rules
37
+
38
+
- type hints required everywhere (Python and TypeScript)
39
+
- async everywhere — never block the event loop (`anyio`/`aiofiles`)
40
+
- lowercase aesthetic in naming, docs, commits
41
+
- imports at the top of files — only defer to break circular deps
42
+
- never hardcode ATProto NSIDs — they're environment-aware via settings
43
+
- session IDs in HttpOnly cookies — never use localStorage for auth
44
+
45
+
## running locally
46
+
47
+
```bash
48
+
uv sync && cd frontend && bun install && cd ..
49
+
cp backend/.env.example backend/.env
50
+
# edit backend/.env — needs DATABASE_URL at minimum
51
+
52
+
just dev-services # redis
53
+
just backend run # port 8001
54
+
just frontend run # port 5173
55
+
```
56
+
57
+
see `backend/.env.example` for all env vars. see `docs-internal/local-development/setup.md` for detailed walkthrough.
58
+
59
+
## environment variables
60
+
61
+
the backend requires a `.env` file. key vars:
62
+
63
+
- `DATABASE_URL` — postgres connection (Neon dev instance or local)
64
+
- `ATPROTO_CLIENT_ID`, `ATPROTO_CLIENT_SECRET`, `ATPROTO_REDIRECT_URI` — OAuth config
65
+
- `STORAGE_BACKEND` — "filesystem" for local dev (no R2 needed)
66
+
- `DOCKET_URL` — redis URL for background tasks (optional, falls back to asyncio)
67
+
68
+
## useful commands
69
+
70
+
```
71
+
just backend run # start backend (hot reload)
72
+
just frontend run # start frontend (hot reload)
73
+
just dev-services # start redis
74
+
just backend test # run tests (isolated postgres + redis via docker)
75
+
just backend lint # type check + ruff
76
+
just frontend check # svelte type check
77
+
just backend migrate-up # apply migrations
78
+
just backend migrate "msg" # create migration
79
+
```
80
+
81
+
## project structure
82
+
83
+
```
84
+
backend/src/backend/
85
+
├── api/ # public endpoints
86
+
├── _internal/ # auth, PDS, uploads
87
+
├── models/ # SQLAlchemy schemas
88
+
├── storage/ # R2 and filesystem
89
+
└── utilities/ # config, helpers
90
+
91
+
frontend/src/
92
+
├── routes/ # pages (+page.svelte, +page.server.ts)
93
+
└── lib/ # components & state (.svelte.ts)
94
+
```
95
+
96
+
## further reading
97
+
98
+
- `docs-internal/` — detailed architecture, deployment, testing docs
99
+
- `docs/lexicons/overview.md` — ATProto record schemas
100
+
- `backend/.env.example` — all configuration options