Cairn
GitHubDashboard

Contributing

Cairn is open source and contributions are welcome. This page is the documentation-site view; the canonical guide is CONTRIBUTING.md at the repo root, and all contributors agree to the Code of Conduct.

Looking for something substantial to own? See Roadmap & help wanted for the bigger projects we'd love help with.

Before you start

  • Read Architecture to find your way around the codebase.
  • For anything non-trivial, open an issue first to align on the approach.
  • Security issues go through SECURITY.md, never a public issue.

Set up a dev environment

You need Node 20+, pnpm 9, and a Postgres database. The full setup (GitHub App, keys, etc.) is in Self-hosting. Once .env is filled in:

pnpm install
pnpm db:push

# three terminals:
npx inngest-cli@latest dev   # background jobs
pnpm dev                     # web app on :3000
pnpm --filter worker dev     # worker on :3100

UI-only changes (landing page, most of the dashboard) usually only need pnpm dev.

Before you push

CI runs format-check, lint, typecheck, and build. Run them locally:

pnpm check-types
pnpm lint
pnpm format
pnpm build

Conventions

  • Branches: type/short-desc — feat|fix|chore|docs|refactor|test|style|perf|ci|build|revert.
  • Commits: Conventional Commits (type(scope): subject), enforced by commitlint.
  • Schema changes: edit packages/db/src/schema, then pnpm db:generate (migration) or pnpm db:push (dev). Note any migration in your PR.
  • Match the surrounding code's style, naming, and comment density.

Pull requests

  1. Fork, branch from main, keep the diff focused.
  2. Fill in the PR template; describe what and why.
  3. Make sure CI is green.
  4. A maintainer reviews. Smaller, clear diffs merge faster.

Contributor License Agreement

Because Cairn offers a managed edition on top of the open-source core, by opening a pull request you agree to the Contributor License Agreement. You keep copyright of your work and grant Cairn a broad license to use it, including in the hosted version. This keeps the project sustainable while everything stays open source under AGPL-3.0. See Licensing.