besaid.zone
+69
CONTRIBUTING.md
+69
CONTRIBUTING.md
···
1
+
# Contributing to Disco Stu
2
+
3
+
Thanks for your interest in contributing! This document gives a short quickstart and guidelines to help you get changes ready for review.
4
+
5
+
## Quickstart
6
+
7
+
1. Fork the repository and create a feature branch from `main`:
8
+
9
+
```bash
10
+
git checkout -b feat/describe-thing
11
+
```
12
+
13
+
2. Install dependencies:
14
+
15
+
```bash
16
+
pnpm install
17
+
```
18
+
19
+
3. Run the app you are working on (examples):
20
+
21
+
```bash
22
+
# Bot
23
+
pnpm bot
24
+
25
+
# Tapper
26
+
pnpm tap
27
+
28
+
# Web
29
+
pnpm web
30
+
31
+
# Build everything
32
+
pnpm build
33
+
```
34
+
35
+
4. Run typechecks and format/lint before pushing:
36
+
37
+
```bash
38
+
pnpm typecheck
39
+
pnpm lint
40
+
pnpm format
41
+
```
42
+
43
+
## Development workflow
44
+
45
+
- Work on a small, focused branch per change.
46
+
- Keep commits atomic and with clear messages (imperative tense): `add ping command`, `fix db migration`.
47
+
- Rebase or squash as appropriate to keep history clean for PRs.
48
+
49
+
## Tests, linting, and formatting
50
+
51
+
- This repo uses `oxfmt` and `oxlint` at the workspace root. Run them locally before opening a PR.
52
+
- Run TypeScript checks with `pnpm typecheck`.
53
+
54
+
## Submitting a PR
55
+
56
+
- Open a pull request against `main` with a clear description of the change and why it’s needed.
57
+
- Include any relevant reproduction steps, screenshots, or logs.
58
+
- If your change affects runtime behavior, add or update documentation in `README.md`.
59
+
- Link any related issue numbers in the PR description.
60
+
61
+
## Commit message guidance
62
+
63
+
- Use short, descriptive commit messages.
64
+
- Prefer present-tense verbs: `add`, `fix`, `update`.
65
+
66
+
## Reporting bugs
67
+
68
+
- Open an issue with steps to reproduce, expected vs actual behavior, and relevant logs or error messages.
69
+
+148
-2
README.md
+148
-2
README.md
···
1
-
# Teal.fm Discord Bot
1
+
# Disco Stu - Teal.fm Discord Bot
2
+
3
+
This repository contains the Disco Stu Discord bot, supporting services, and shared packages used by the project. The workspace is a monorepo managed with pnpm and TypeScript; each app and package has its own package.json and build/dev scripts.
4
+
5
+
**Repository Structure**
6
+
- `apps/` : Application code (runtime programs and services)
7
+
- `bot/` : Discord bot (commands, deploy script)
8
+
- `tapper/` : Backfill client for Tap service
9
+
- `web/` : Web server to handle OAuth
10
+
- `packages/` : Shared libraries used across apps
11
+
- `common/` : Logging and shared utilities
12
+
- `database/` : Database access, Kysely migrations and seed scripts
13
+
- `tsconfig/` : Shared TypeScript config packages
14
+
15
+
**Apps**
16
+
- `apps/bot` — Discord bot
17
+
- Entry: `apps/bot/main.ts`.
18
+
- Key files: `apps/bot/commands/*.ts` (command handlers), `apps/bot/deploy-commands.ts` (registers commands with Discord), `apps/bot/discord.d.ts` (types).
19
+
- Useful scripts (see [apps/bot/package.json](apps/bot/package.json)):
20
+
- `dev` — run bot in watch mode with `tsx --watch main.ts`
21
+
- `deploy-commands` — run `deploy-commands.ts` to push slash-command definitions to Discord
22
+
- `build` — compile TypeScript to `dist/`
23
+
- `start` — run compiled bot from `dist/main.js`
24
+
25
+
- `apps/tapper` — Tap client
26
+
- Entry: `apps/tapper/index.ts`.
27
+
- Purpose: Interact with tap service running at https://tap.xero.systems
28
+
- Useful scripts (see [apps/tapper/package.json](apps/tapper/package.json)):
29
+
- `dev` — runs `NODE_ENV=development tsx index.ts`
30
+
- `start` — run compiled `dist/index.js` in production
31
+
32
+
- `apps/web` — Web server
33
+
- Entry: `apps/web/index.ts`.
34
+
- Integrates with AT Protocol APIs and provides OAuth/web endpoints.
35
+
- Useful scripts (see [apps/web/package.json](apps/web/package.json)):
36
+
- `dev` — `tsx --watch index.ts` to run in dev
37
+
- `build` — compile TypeScript
38
+
- `start` — run compiled server from `dist/index.js`
39
+
40
+
**Packages**
41
+
- `packages/common` — shared utilities and logging
42
+
- Exports logging helpers and other common utilities used by apps. Build with `pnpm --filter @tealfmbot/common build` or use workspace protocol.
43
+
- Scripts: `build`, `build:watch`, `typecheck` (see [packages/common/package.json](packages/common/package.json)).
44
+
45
+
- `packages/database` — Kysely-based database layer
46
+
- Contains DB helpers, `migrate.ts`, `seed.ts`, and Kysely codegen support.
47
+
- Scripts (see [packages/database/package.json](packages/database/package.json)):
48
+
- `migrate` — run `kysely migrate latest` to apply migrations
49
+
- `codegen` — run `kysely-codegen` to regenerate `database.d.ts`
50
+
- `seed` — run `tsx seed.ts` to seed data
51
+
- `build`, `build:watch`, `typecheck`
52
+
53
+
- `packages/tsconfig` — shared TypeScript configs
54
+
- Provides base tsconfig settings shared by other packages.
55
+
56
+
**Top-level scripts** (see [package.json](package.json))
57
+
- `pnpm bot` — start the bot dev script (`pnpm --filter bot dev`)
58
+
- `pnpm tap` — start the tapper dev script (`pnpm --filter tapper dev`)
59
+
- `pnpm web` — start the web app dev script (`pnpm --filter web dev`)
60
+
- `pnpm build` — run `pnpm -r build` to build all packages and apps
61
+
- `pnpm build:watch` — run watch builds across the monorepo
62
+
- `pnpm dev:all` — runs `dev` for all apps under `apps/`
63
+
- `pnpm typecheck` — run TypeScript checks across apps
64
+
- `pnpm lint` — run `oxlint` (project linter)
65
+
- `pnpm format` — run `oxfmt` to format code
2
66
3
-
who knows if i'll finish this
67
+
Developer workflow
68
+
- Install dependencies: `pnpm install` (pnpm v10+ recommended)
69
+
- Develop a single app:
70
+
- Bot: `pnpm --filter bot dev` or `pnpm bot`
71
+
- Tapper: `pnpm --filter tapper dev` or `pnpm tap`
72
+
- Web: `pnpm --filter web dev` or `pnpm web`
73
+
- Develop all apps concurrently: `pnpm dev:all`
74
+
- Build all packages and apps: `pnpm build`
75
+
76
+
Database tasks
77
+
- Migrations are managed via Kysely. Run migrations from the `packages/database` package:
78
+
79
+
```bash
80
+
pnpm --filter @tealfmbot/database migrate
81
+
```
82
+
83
+
- Regenerate types (codegen):
84
+
85
+
```bash
86
+
pnpm --filter @tealfmbot/database codegen
87
+
```
88
+
89
+
Docker / deployment
90
+
- `Dockerfile` and `docker-compose.prod.yml` are included for building and deploying container images.
91
+
- The repository contains `build-and-publish-images.sh` to build and publish images (will be a CI thing eventually).
92
+
93
+
Project tooling
94
+
- `lefthook.yml` configures git hooks.
95
+
- `oxlint` and `oxfmt` are used for linting and formatting.
96
+
97
+
Notes & tips
98
+
- To deploy Discord commands after changes, run the bot package `deploy-commands` script:
99
+
100
+
```bash
101
+
pnpm --filter bot deploy-commands
102
+
```
103
+
104
+
**Contributing & Quickstart**
105
+
106
+
If you want to contribute or get a local development environment running quickly, follow these steps:
107
+
108
+
- Clone the repo and install dependencies:
109
+
110
+
```bash
111
+
git clone https://tangled.org/dane.is.extraordinarily.cool/tealfmbot
112
+
cd tealfmbot
113
+
pnpm install
114
+
```
115
+
116
+
- Start individual apps in development:
117
+
118
+
```bash
119
+
# Bot
120
+
pnpm bot
121
+
122
+
# Tapper
123
+
pnpm tap
124
+
125
+
# Web
126
+
pnpm web
127
+
```
128
+
129
+
- Start all apps concurrently (monorepo dev):
130
+
131
+
```bash
132
+
pnpm dev:all
133
+
```
134
+
135
+
- Build everything:
136
+
137
+
```bash
138
+
pnpm build
139
+
```
140
+
141
+
- Run TypeScript checks and format/lint before opening a PR:
142
+
143
+
```bash
144
+
pnpm typecheck
145
+
pnpm lint
146
+
pnpm format
147
+
```
148
+
149
+
Please open issues or PRs for new features, and include clear reproduction steps and expected behavior.