Skip to main content

Contributing

Workloom is open source and welcomes contributions. Whether you're fixing a bug, adding a provider adapter, improving documentation, or proposing a new feature — here's how to get started.

Development Setup​

Prerequisites​

  • Node.js >= 22
  • pnpm 11
  • Git

Getting Started​

# Clone the repository
git clone https://github.com/catesandrew/workloom-baro.git
cd workloom-baro

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run tests
pnpm test

# Type check
pnpm typecheck

# Lint
pnpm lint

Running Specific Packages​

# Run CLI in development
pnpm --filter @workloom/cli dev

# Test a specific package
pnpm --filter @workloom/renderer test

# Build just the core packages
pnpm --filter @workloom/core --filter @workloom/manifest build

Project Structure​

apps/
  cli/          # The `wl` command-line tool
  web/          # Registry web UI and API
  docs/         # This documentation site

packages/
  core/         # Domain primitives — start here
  manifest/     # Zod schemas — the data model
  renderer/     # Render engine — the core logic
  provider-*/   # Provider adapters
  drift/        # Drift detection
  ...

Start with packages/core/ and packages/manifest/ to understand the domain model. Then read packages/renderer/ for the core render pipeline.

How to Contribute​

Bug Fixes​

  1. Open an issue describing the bug
  2. Fork + branch (fix/description)
  3. Write a failing test
  4. Fix the bug
  5. Submit a PR referencing the issue

New Features​

  1. Open an issue or discussion describing the feature
  2. Wait for feedback (helps avoid wasted work)
  3. Fork + branch (feat/description)
  4. Implement with tests
  5. Submit a PR

Provider Adapters​

Adding a new provider adapter is one of the best ways to contribute:

  1. Create packages/provider-yourprovider/
  2. Add test fixtures in the package
  3. Implement the adapter interface from @workloom/renderer
  4. Add snapshot tests for rendered output
  5. Document provider capabilities

Documentation​

Documentation lives in apps/docs/. Run locally with:

cd apps/docs
pnpm start

Code Standards​

  • TypeScript strict mode — no any, no implicit returns
  • Vitest for all tests
  • Zod for runtime validation
  • No comments unless explaining a non-obvious "why"
  • Conventional commits — feat:, fix:, docs:, refactor:

Testing​

# Run all tests
pnpm test

# Run with coverage
pnpm test -- --coverage

# Run specific test file
pnpm --filter @workloom/renderer test -- render.test.ts

Tests are fixture-driven. Check fixtures/ at the repo root for workspace, package, drift, provider, and telemetry fixtures.

Architecture Decision Records​

Major architectural decisions are documented in docs/adr/. If your contribution changes architecture, add or update an ADR.