CONTRIBUTING.md

Contributing

Workflow

1. Create a branch from main.
2. Make changes locally.
3. Run:

npm install
npm run db:bootstrap:local
npm run typecheck
npm run test
npm run format
npm run lint
npm run build

If you changed user-facing flows or browser interactions, also run:

npm run test:e2e

4. Open a pull request.
5. Wait for CI to pass.
6. Review the preview deployment if one is enabled for the repository.
7. Merge to main.

Merges to main are intended to trigger a production deploy.

Releases

• Keep CHANGELOG.md and package.json in sync when preparing a release PR.
• Use 0.x.x for normal minor/patch releases while the project is still pre-1.0.
• If the release is a major milestone or materially changes the product scope, bump the middle digit such as 0.2.0.
• Otherwise, use a patch release such as 0.1.1.
• Ask explicitly which release level is intended if it is not obvious from the scope of the work.

Local development

Start here:

• README.md
• docs/local-development.md

Database changes

• Put schema changes in src/lib/db/schema.ts
• Generate or add the matching SQL migration in drizzle
• Run npm run db:migrate
• Do not leave the code expecting a schema change that is not represented by a migration

The app checks the latest applied migration at runtime and fails early if the local database is behind.

Pull request expectations

• Keep changes focused.
• Include tests when you change behavior.
• Run npm run format before npm run lint. This repo has been seeing avoidable AI-generated formatting drift, and Biome lint is much cleaner after formatting first.
• If a change affects Twitch auth, EventSub, playlist mutations, or migrations, call that out in the PR description.
• If a change affects deployment or Cloudflare bindings, update the docs in the same PR.

Before enabling open contributions

Recommended repository settings:

• protect main
• require pull requests for merge
• require the CI workflow to pass
• require at least one review before merge
• restrict direct pushes to main