# Contributing

How to work in this repo. The planning folder is the source of truth; read it
before writing code.

## The planning loop

`/planning` drives all implementation (see [`CLAUDE.md`](../../CLAUDE.md)):

1. Read [`planning/MASTER_PLAN.md`](../../planning/MASTER_PLAN.md) — vision + phases.
2. `bootspring build next` — queue the next task.
3. Read [`planning/TODO.md`](../../planning/TODO.md) — the task + its acceptance criteria.
4. Implement against the acceptance criteria.
5. Check off `TODO.md`, run `bootspring build done`, document any deviation.

One task at a time; finish the current one before starting the next.

## Code style

- **JavaScript** for all server code (ES modules). The editor is TypeScript/React.
- Keep files focused and ideally **under 300 lines**.
- Match existing conventions — read the neighbours before adding a module.
- Server modules follow the **injectable-`query` pattern** (default `dbQuery`)
  so they're unit-testable without a database. See
  [Client-Operations Layer](client-ops.md) for the canonical shape.

## Testing

```
npm test          # node --test over test/*.test.js
npm run lint      # scripts/check-syntax.mjs — syntax/parse check
```

Add tests next to the module under `test/`. Pure logic (e.g. booking's
`generateSlots`) should be tested directly with an injected fake `query`; never
require a live DB in unit tests. Keep the suite green before committing.

## Migrations

Additive, hand-written SQL only — see [Data Model](data-model.md):

- New file `migrations/0NN_name.sql`, migrator-owned, wrapped in `begin/commit`.
- Use `create table if not exists` / `if not exists` everywhere (idempotent).
- Never edit an already-applied migration; add a new one.
- Apply with `npm run db:migrate` over the tunnel ([Deployment](deployment.md)).
- Prod migrations require explicit human authorization.

## Commits

- **Conventional commits**: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`.
- Atomic — one logical change per commit.
- **NEVER add `Co-Authored-By` or any AI attribution** (project rule in
  `CLAUDE.md`).
- Never commit secrets, API keys, or credentials.
- Bump `BUILD_VERSION` in [`src/api.js`](../../src/api.js) on server-affecting
  changes so the `/api/health` deploy check stays meaningful.

## Pre-commit

`bootspring quality pre-commit` runs the quality gates. At minimum: `npm test`
and `npm run lint` must pass.

Related: [Architecture](architecture.md) · [Data Model](data-model.md) · [Deployment](deployment.md).