audio streaming app
plyr.fm
docs: rewrite skill as action-oriented playbook, link contributing from developers (#1040)
- skill now points at existing resources (CLAUDE.md, .env.example,
docs-internal/setup.md) instead of restating their contents
- structured as a 5-step playbook: orient, fork, change, validate, PR
- add contributing link at bottom of developers page
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
authored by
Claude Opus 4.6
and committed by
GitHub
bb82aa4b
0d834e61
+4
docs/developers.md
+4
docs/developers.md
···
70
70
## ATProto lexicons
71
71
72
72
all plyr.fm data uses custom ATProto lexicons under the `fm.plyr` namespace. see the [lexicons overview](/lexicons/overview/) for schemas and record types.
73
+
74
+
## contributing
75
+
76
+
plyr.fm is open source. see the [contributing guide](/contributing/) to get involved.
+25
-73
skills/contribute/SKILL.md
+25
-73
skills/contribute/SKILL.md
···
6
6
repo: https://github.com/zzstoatzz/plyr.fm
7
7
---
8
8
9
-
# contributing to plyr.fm
9
+
# how to contribute to plyr.fm
10
10
11
-
## orientation
11
+
## step 1: orient yourself
12
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
13
+
read these files in the repo — they have everything you need:
16
14
17
-
## stack
15
+
- `CLAUDE.md` — project rules, stack, structure, conventions
16
+
- `STATUS.md` — active tasks and known issues
17
+
- `backend/.env.example` — all environment variables with comments
18
+
- `docs-internal/local-development/setup.md` — full local dev walkthrough
18
19
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)
20
+
check [open issues](https://github.com/zzstoatzz/plyr.fm/issues) for things to work on.
24
21
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
22
+
## step 2: fork and set up
46
23
47
24
```bash
25
+
gh repo fork zzstoatzz/plyr.fm --clone
26
+
cd plyr.fm
48
27
uv sync && cd frontend && bun install && cd ..
49
28
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
29
+
# edit backend/.env — DATABASE_URL is required, see the file for details
55
30
```
56
31
57
-
see `backend/.env.example` for all env vars. see `docs-internal/local-development/setup.md` for detailed walkthrough.
32
+
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.
58
33
59
-
## environment variables
34
+
## step 3: make your change
60
35
61
-
the backend requires a `.env` file. key vars:
36
+
- branch from `main`
37
+
- for bug fixes, add a regression test
38
+
- run `just --list` to see available commands (linting, tests, etc.)
62
39
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)
40
+
## step 4: validate
67
41
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
42
+
```bash
43
+
just backend lint # python: type check + ruff
44
+
just frontend check # svelte: type check
45
+
just backend test # runs tests with isolated docker postgres + redis
79
46
```
80
47
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
-
```
48
+
## step 5: open a PR
95
49
96
-
## further reading
50
+
open a PR from your fork to `zzstoatzz/plyr.fm:main`. describe what changed and why.
97
51
98
-
- `docs-internal/` — detailed architecture, deployment, testing docs
99
-
- `docs/lexicons/overview.md` — ATProto record schemas
100
-
- `backend/.env.example` — all configuration options
52
+
PRs are the only way changes land — the main branch is protected.