Skip to content

Commit e3fe7ee

Browse files
IamCoder18IamCoder18
committed
docs: improve contributing and environment documentation
1 parent 46563ad commit e3fe7ee

2 files changed

Lines changed: 590 additions & 0 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 210 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,210 @@
1+
# Contributing to Kilo Code Cloud
2+
3+
See [the Documentation for details on contributing](https://kilo.ai/docs/contributing).
4+
5+
## TL;DR
6+
7+
There are lots of ways to contribute to the project:
8+
9+
- **Code Contributions:** Implement new features or fix bugs
10+
- **Documentation:** Improve existing docs or create new guides
11+
- **Bug Reports:** Report issues you encounter
12+
- **Feature Requests:** Suggest new features or improvements
13+
- **Community Support:** Help other users in the community
14+
15+
The Kilo Community is [on Discord](https://kilo.ai/discord).
16+
17+
## Prerequisites
18+
19+
- **Node.js 24** (`.nvmrc` pins `24.14.1`) — required for all packages.
20+
- **pnpm 11.1.2** — use Corepack so the active version matches `package.json` `packageManager`:
21+
```bash
22+
corepack enable
23+
corepack prepare pnpm@11.1.2 --activate
24+
```
25+
- **Docker / Docker Compose** — required to run the local PostgreSQL database.
26+
27+
## Developing Kilo Code Cloud
28+
29+
### 1. Install dependencies
30+
31+
```bash
32+
nvm install && nvm use
33+
pnpm install
34+
```
35+
36+
### 2. Set up environment variables
37+
38+
If you do not have Vercel access, copy `.env.local.example` to `.env.local` and set at least:
39+
40+
- `NEXTAUTH_SECRET`: `openssl rand -base64 32`
41+
- `INTERNAL_API_SECRET`: `openssl rand -base64 32`
42+
43+
Then run `pnpm dev:env` to derive worker `.dev.vars` files from `.env.local`.
44+
45+
### 3. Start the database
46+
47+
```bash
48+
docker compose -f dev/docker-compose.yml up -d
49+
```
50+
51+
This starts PostgreSQL on `localhost:5432` with user `postgres` / password `postgres`.
52+
53+
### 4. Run database migrations
54+
55+
```bash
56+
pnpm drizzle migrate
57+
```
58+
59+
Re-run this after pulling new migrations. To fully reset:
60+
61+
```bash
62+
pnpm dev:db:reset
63+
pnpm drizzle migrate
64+
```
65+
66+
To smoke-test migrations from a fresh database:
67+
68+
```bash
69+
pnpm drizzle:verify-bootstrap
70+
```
71+
72+
### 5. Start the development server
73+
74+
```bash
75+
pnpm dev:start
76+
```
77+
78+
This launches a tmux dashboard with the Next.js app and local infrastructure. The web app is available at http://localhost:3000.
79+
80+
To stop all services:
81+
82+
```bash
83+
pnpm dev:stop
84+
```
85+
86+
## Verifying Your Setup
87+
88+
```bash
89+
pnpm test
90+
```
91+
92+
All tests should pass against the local PostgreSQL database.
93+
94+
## Repo Layout
95+
96+
Key locations:
97+
98+
- `apps/web/` — Next.js web application and main UI code
99+
- `apps/mobile/` — React Native mobile app
100+
- `services/` — Cloudflare Worker services (KiloClaw, cloud agent, etc.)
101+
- `packages/` — shared libraries (`@kilocode/db`, `@kilocode/trpc`, `@kilocode/worker-utils`)
102+
- `dev/` — local dev tooling (docker-compose, tmux scripts, env sync, seed data)
103+
- `scripts/` — CI and one-off scripts
104+
- `packages/db/src/schema.ts` — database schema; migrations in `packages/db/src/migrations/`
105+
- `apps/web/src/routers/` — tRPC routers
106+
107+
## Mock / seed data
108+
109+
The repo includes a seed runner for creating local fixtures via `pnpm dev:seed`. Run it with no args to see all available topics.
110+
111+
### App
112+
113+
- `pnpm dev:seed app:create-user <name> <email>` — creates a `kilocode_users` row with a real Stripe test customer, pre-bypassing onboarding gates so you can use the app immediately.
114+
- `pnpm dev:seed app:add-credits <user-id> <usd>` — grants credits to an existing user, updating the `total_microdollars_acquired` balance and creating a `credit_transactions` row. Supports `--paid`/`--free`, `--category`, `--expires-in-days`, etc. Useful for testing billing and credit flows without manual DB edits.
115+
116+
### KiloClaw
117+
118+
- `pnpm dev:seed kiloclaw:fake-instance <user-id> [options]` — creates a fake personal KiloClaw instance + subscription in the database only (no real container or Worker). Before creating, it retires any prior fake personal instances for that user. Supports `--plan=trial|standard|commit` and `--days=<n>`. For paid plans, it also grants enough credits to cover the plan cost and then deducts the subscription cost.
119+
- `pnpm dev:seed kiloclaw:fake-org-instance <user-id> <org-id> [options]` — same as above, but creates an instance belonging to an organization rather than a personal account.
120+
- `pnpm dev:seed kiloclaw:referrals-<scenario>` — seeds KiloClaw referral fixtures. Topics include `referrals-happy-path`, `referrals-pending-referrer`, `referrals-cap-boundary`, and `referrals-support-override`.
121+
- `pnpm dev:seed kiloclaw-billing:inactive-trials` — seeds inactive-trial billing fixtures. One user is provisioned through the real KiloClaw worker endpoint (`/api/platform/provision`), while others are DB-only rows representing users in recently-started, support-marked, or eligible inactive-trial states.
122+
123+
## Common Development Commands
124+
125+
| Command | Description |
126+
|---|---|
127+
| `pnpm dev:start` | Start all local services in a tmux dashboard |
128+
| `pnpm dev:stop` | Stop the tmux session and all services |
129+
| `pnpm dev:status` | Live status of running services |
130+
| `pnpm dev:restart` | Restart a running service |
131+
| `pnpm dev:env` | Sync `.dev.vars` files from `.env.local` |
132+
| `pnpm test` | Run the Jest test suite |
133+
| `pnpm test:e2e` | Run Playwright end-to-end tests |
134+
| `pnpm typecheck` | Run TypeScript type checking |
135+
| `pnpm lint` | Lint all source files |
136+
| `pnpm format` | Auto-format all supported files with oxfmt |
137+
| `pnpm validate` | Run typecheck, lint, and tests together |
138+
| `pnpm drizzle migrate` | Apply pending database migrations |
139+
| `pnpm drizzle generate` | Generate a new migration after schema changes |
140+
141+
## Tests for a specific package
142+
143+
```bash
144+
pnpm --filter <package> test
145+
```
146+
147+
## Cloudflare Workers
148+
149+
Workers are started individually as needed:
150+
151+
```bash
152+
cd services/<worker-name>
153+
pnpm dev # or: wrangler dev
154+
```
155+
156+
Use `pnpm dev:start <group>` to run groups of related services via the tmux dashboard. The easiest way to manage workers during development is through the dev dashboard.
157+
158+
## Fake Login (Local Auth)
159+
160+
Sign in without real OAuth:
161+
162+
```
163+
http://localhost:3000/users/sign_in?fakeUser=<email>
164+
```
165+
166+
Use an `@admin.example.com` email for fake admin access:
167+
168+
```
169+
http://localhost:3000/users/sign_in?fakeUser=<email>@admin.example.com
170+
```
171+
172+
Append `callbackPath` to redirect after login:
173+
174+
```
175+
http://localhost:3000/users/sign_in?fakeUser=<email>&callbackPath=/profile
176+
```
177+
178+
## Git Workflow
179+
180+
- Direct commits to `main` are blocked. Always work on a feature branch.
181+
- The pre-push hook runs `pnpm format:check`, `pnpm lint`, and `pnpm typecheck --changes-only`.
182+
183+
## Pull Requests
184+
185+
### PR Titles
186+
187+
Use conventional commit style PR titles:
188+
189+
- `feat: add MCP settings tab`
190+
- `fix: correct Windows path handling`
191+
- `docs: clarify issue template requirements`
192+
- `chore: bump TypeScript version`
193+
- `refactor: extract diff renderer into a hook`
194+
- `test: cover ServerManager orphan cleanup`
195+
196+
### Contribution Ownership and AI Assistance
197+
198+
AI and coding agents are allowed, but contributors own the work they submit. Before requesting review, make sure you personally understand the change, have tested it appropriately, can explain the diff, and understand how it interacts with the affected packages and the rest of the repo.
199+
200+
Maintainers may close PRs that appear to be submitted without credible contributor ownership or understanding, including AI-assisted work that the contributor cannot explain or has not meaningfully reviewed.
201+
202+
### Tracker Use and Automation
203+
204+
Do not submit batches of agent-generated, untested, or weakly reviewed PRs.
205+
206+
Please keep concurrent PRs focused and limited. As a rule, open no more than three PRs at a time, especially if you are a new contributor. Prioritize high-impact or high-priority issues first instead of opening many speculative fixes. If a contributor opens a large batch of low-value or duplicative PRs, maintainers may close the batch and ask the contributor to choose one PR to reopen, focus, and bring up to the documented review bar before submitting more.
207+
208+
For issues, do not mass-create tickets through automation or agents. Search existing issues first, open issues only when you have enough context for someone to act, and prioritize the most important reports instead of filing every possible finding. Maintainers may close duplicate, low-signal, automated, or weakly reviewed issues without action.
209+
210+
Repeated disregard of this contribution guide, or high-volume automated or agent-generated tracker spam across issues or PRs, may result in maintainers blocking the responsible account.

0 commit comments

Comments
 (0)