Skip to main content

Contributing

This page shows you how to set up the repositories, run the build and tests, and get a pull request accepted on SLAW or Botfather.

Both products are pnpm monorepos with the same toolchain, so the workflow below applies to either. Small, focused fixes and docs improvements are the fastest path to a merge.

Prerequisites

You need Node.js 20+ and pnpm 9.15+ (the repos pin pnpm@9.15.4 via packageManager). Use corepack enable to get the pinned pnpm version automatically.

The two repositories​

RepositoryWhat it isClone
SLAWThe local control plane — Node.js server, React UI, and CLI.git clone https://github.com/slaw-ai/slaw.git
BotfatherThe self-hosted fleet control tower for SLAW instances.git clone the Botfather repository

See What is SLAW and What is Botfather? for how the two fit together.

Repo layout​

SLAW is a pnpm workspace. The top-level members are:

  • packages/* — shared libraries, adapters (packages/adapters/*), and plugins (packages/plugins/*).
  • server — the API server and orchestration engine.
  • ui — the React + Vite dashboard.
  • cli — the slaw command-line tool.

Botfather follows the same shape: packages/protocol (the instance ⇄ tower wire contract), packages/db (Drizzle schema and migrations), server (the ingest and admin API), and ui (the dashboard).

Build and test — SLAW​

From the repository root:

pnpm install          # install workspace dependencies
pnpm dev              # full dev (API + UI, watch mode)
pnpm build            # build all packages
pnpm typecheck        # type checking
pnpm test             # cheap default test run (Vitest only)
pnpm test:e2e         # Playwright browser suite (run when touching those flows)

pnpm dev starts the API on http://localhost:3100 with an embedded PostgreSQL database — no separate database setup. Note that pnpm test does not run Playwright; browser suites stay separate. The full guide is in doc/DEVELOPING.md.

Build and test — Botfather​

Botfather's protocol and db packages must build first:

pnpm install
pnpm --filter @slaw/botfather-protocol build
pnpm --filter @slaw-botfather/db build
pnpm --filter @slaw-botfather/db exec drizzle-kit migrate   # against Postgres on :54330
pnpm --filter @slaw-botfather/server dev                    # :8400
pnpm --filter @slaw-botfather/ui dev                        # :5174 (proxies /api → :8400)

Tests use an in-process Postgres (pglite), so they run without a database:

pnpm --filter @slaw-botfather/server test

Versioning​

SLAW releases use calendar versioning — vYYYY.MDD.0, where the date is the release day. Released versions and their notes live in the repository's releases/ directory and are summarised on the Changelog.

Getting a pull request accepted​

There are two paths, and both share the same quality bar.

Path 1 — small, focused changes (fastest to merge). Fix one clear thing, touch the fewest files possible, keep it quick to review.

Path 2 — bigger or impactful changes. Open a GitHub Discussion first, agree on rough direction, then build. Include before/after screenshots (or a short video) for any UI or behaviour change. Uncoordinated feature PRs against the core product may be closed regardless of quality — that is about roadmap ownership, not effort. Check ROADMAP.md first, and prefer building extensions with the plugin system.

Requirements for every PR​

  • Use the PR template. Every PR must follow .github/PULL_REQUEST_TEMPLATE.md, with all required sections: Thinking Path, What Changed, Verification, Risks, Model Used, and the Checklist. If your tooling bypasses the template, copy it in manually.
  • Model Used (required). State which AI model produced or assisted the change — provider, exact model ID/version, context window, and relevant capabilities. If no AI was used, write "None — human-authored." This applies to every contributor.
  • Tests must pass. Run them locally first and confirm CI is green.
  • Greptile 5/5. The PR must reach a 5/5 Greptile score with all Greptile comments addressed before it can merge.

General etiquette​

  • One PR = one logical change.
  • Write clear commit messages and a meaningful PR title and description.
  • Be kind in discussions.

Questions? Ask in GitHub Discussions.

Next steps​