61 lines
2.5 KiB
Markdown
61 lines
2.5 KiB
Markdown
# Contributing
|
|
|
|
Thanks for your interest! This repo is a deterministic website **compiler**
|
|
(`compiler/`) plus a hosted **service layer** (`packages/`). The benchmarks and
|
|
fixtures double as the regression suite.
|
|
|
|
## Setup
|
|
|
|
```bash
|
|
npm install # installs all workspaces
|
|
npx playwright install chromium # for capture / browser-gated tests
|
|
```
|
|
|
|
## Develop
|
|
|
|
- **Service layer** lives in `packages/*` (TypeScript, run via `tsx`, no build step).
|
|
- `npm run typecheck` — type-checks every workspace.
|
|
- `npm test` — runs every workspace's tests (node:test). Tests gate themselves:
|
|
browser tests skip without Chromium; Postgres tests use `TEST_DATABASE_URL` or a
|
|
throwaway local Postgres (root only).
|
|
- Start locally: `docker compose up -d` then `npm run dev:api` / `npm run dev:worker`
|
|
(see [`docs/SERVICE.md`](docs/SERVICE.md)).
|
|
- **Compiler** lives in `compiler/`. See the root [`README.md`](README.md) for the
|
|
architecture overview.
|
|
The service layer depends on it **only** through `compiler/src/index.ts` (the
|
|
library barrel) — do not import compiler internals from `packages/*`.
|
|
|
|
## Ground rules
|
|
|
|
- **Don't change the compiler's clone semantics** from the service layer. The
|
|
service is a wrapper; clone output must stay byte-deterministic (rubric Gate 6).
|
|
Golden-file tests rely on this.
|
|
- Every change should keep `npm run typecheck` and `npm test` green.
|
|
- Database schema changes: edit `packages/db/src/schema.ts`, then
|
|
`npm run db:generate` to produce a migration, and commit it.
|
|
- Keep new code in the style of the surrounding code (naming, comments, idiom).
|
|
|
|
## Database migrations
|
|
|
|
```bash
|
|
npm run db:generate # after editing the Drizzle schema → writes packages/db/migrations/*
|
|
npm run db:migrate # applies to $DATABASE_URL
|
|
```
|
|
|
|
## Pull requests
|
|
|
|
1. Fork / branch off `main`.
|
|
2. Make your change with tests; keep `npm run typecheck` and `npm test` green.
|
|
3. Open a PR and fill in the [PR template](.github/pull_request_template.md). CI
|
|
(typecheck + the full suite, with Postgres + Chromium) must pass.
|
|
4. If your change touches the deterministic compiler's clone output, say so and
|
|
include benchmark results (`npm run bench`).
|
|
|
|
By participating you agree to abide by our [Code of Conduct](CODE_OF_CONDUCT.md).
|
|
|
|
## Reporting bugs & security issues
|
|
|
|
- **Bugs / features:** open an issue using the templates.
|
|
- **Security vulnerabilities:** do **not** open a public issue — follow
|
|
[`SECURITY.md`](SECURITY.md) (private GitHub advisory).
|