Contributing

Branches

A fresh branch off origin/main for every PR, fetched first. Squash merges capture a branch at merge time; later commits on the same branch are orphaned and silently do not ship. That has cost four separate fixes, including one that looked merged and was not.

Tests

cd apps/user-gui
DATABASE_URL=... npx tsx src/__tests__/<name>.ts

Real Postgres, no mocks. Tests seed their own data — one suite once passed by coincidence because it read rows a container happened to hold.

Assert the behaviour, not the number. Two credit-allowance tests hardcoded 5,000 and broke every time pricing moved, which invites updating the literal without re-reading what is being asserted. Read it from the catalogue.

Migrations

Forward-only. Never edit one that has run. If it is applied on production, the correction is another migration.

Say why in the comment, not what. The SQL says what.

Before opening a PR

npx tsc --noEmit
npm run build
node scripts/stripe-verify.mjs        # if anything touched pricing

Documentation

If the change alters what a customer sees or does, the documentation change belongs in the same PR. Documentation written a week later is written by someone who has forgotten the detail that mattered.