Contributing#

Vibesboard is open source and contributions are welcome. This page covers the mechanics — branching, commits, and the checks a pull request has to pass. For anything larger than a bug fix or a small correction, open an issue on the GitHub repository first and describe what you want to change; agreeing on an approach before the code is written is cheaper than discovering a mismatch after. Everyone taking part is expected to follow the repository's Code of Conduct.

Set up your environment#

Requirements: Bun 1.2.18, Node.js 22, Docker with Compose, and an OpenAI API key for the platform fallback model.

git clone https://github.com/<your-fork>/vibesboard.git
cd vibesboard
cp .env.example .env
# Edit .env and replace the placeholder credentials and secrets.

bun install
bun run db:setup   # starts Postgres, Adminer, MinIO; migrates and seeds
bun run dev

For the full command reference, port map, and troubleshooting, see Docker Compose. For every configuration value, see Environment variables.

Branching model#

Branch from dev, never from main:

git checkout dev && git pull
git checkout -b feat/short-description

• dev is the staging environment; main is production.
• Feature branches merge into dev through a pull request. As a contributor, dev is always your target — only maintainers open the dev → main release pull request, and that merge is a merge commit rather than a squash, so a feature PR's own branch strategy doesn't need to account for it.
• Releases to main are automated by release-please reading conventional commits to decide version bumps and build the changelog.

Write tests before the implementation. This is a multi-tenant SaaS, so tenant isolation is a correctness requirement, not a nice-to-have — if your change touches data access, add a test proving one workspace cannot reach another's rows. When debugging something non-obvious, find the root cause rather than patching the symptom; a fix that makes a test pass without explaining the original failure usually moves the bug rather than removing it. See Testing for how the suites are organized and Multi-tenancy & RLS for the isolation model itself.

Commit messages#

Use Conventional Commits:

feat(scope): add per-agent model routing
fix(scope): stop leaking the tenant id into the widget payload
chore(scope): bump drizzle to 0.44

feat and fix appear in the changelog and drive version bumps; chore, docs, test, and refactor do not trigger a release. Feature branches are squash-merged into dev, so you do not need to tidy up intermediate commits — but the pull request title becomes the squashed commit message, so it should follow the format above.

Checks your PR must pass#

Run these locally before you push — they are the same gates CI applies on pull requests to dev and main:

bun run lint
bun run format:check
bun run type-check
bun run test           # requires `bun run db:up && bun run db:migrate` first

CI additionally runs two Playwright suites and a production build. Both suites run from apps/web and stub the model at the network boundary with a mock OpenAI server, so they need no API key:

cd apps/web
bun run test:e2e         # specs directly under e2e/
bun run test:e2e:local   # the deep suite under e2e/local/

See Testing for what each suite covers and for running the deep suite locally, including the path that needs no Docker. The E2E suites are heavy; letting CI run them is usually the better trade unless you're actively changing them.

Opening a pull request#

• Target dev.
• Keep the PR focused on one thing. Unrelated cleanups are welcome as a separate PR.
• Fill in the template: what changed, why, and how you verified it. "Tests pass" is less useful than naming the suite and the case that used to fail.

Licensing of contributions#

NordicAgents' original Vibesboard work is released under the MIT License; retained third-party portions are identified in NOTICE. By submitting a pull request you agree that your contribution is licensed under the MIT terms, and that you have the right to license it — it's your own work, or you have permission from whoever owns it. Do not remove or replace third-party copyright and license notices.