FrappDocs
Docs/Guide

Contributing

This guide defines how we work on Frapp: git workflow, commit messages, and the spec‑driven process.

1. Branching model

We use a simple, trunk-focused flow:

  • main — always deployable, contains the latest stable work
  • feature/* — short‑lived branches for individual features or fixes

Example branch names:

  • feature/backwork-redaction-ui
  • feature/events-rbac
  • feature/docs-overhaul

2. Commit messages

Use conventional commits with a short scope when helpful:

type(scope): description

Examples:

  • feat(api): add service hours endpoints
  • refactor: switch api auth to supabase
  • docs(docs): add docker guide

Types:

  • feat — new user‑visible feature
  • fix — bug fix
  • refactor — code change that doesn't alter behavior
  • docs — documentation only
  • chore — tooling, config, or misc maintenance

3. Spec‑driven development

Frapp is explicitly spec‑driven:

  1. Update specs in spec/ first:
    • spec/product.md — high‑level product view
    • spec/behavior.md — feature behavior and edge cases
    • spec/architecture.md — system/data model
  2. Only then implement the behavior in:
    • apps/api (API)
    • apps/web / apps/mobile (UI)
  3. Update docs in apps/docs to reflect the new behavior.
Info

If you ever notice the implementation and specs diverging, treat it as a bug. Either update the code to match the spec, or revise the spec and document the change.

4. Pull requests

When opening a PR:

  • Link to the relevant spec sections you implemented.
  • Describe changes in terms of behavior and domains (e.g. "Backwork upload metadata", not "added 3 columns").
  • List test coverage: unit tests, E2E, and any manual scenarios you ran.
  • Call out any follow‑up work or tech debt explicitly.
  • Fill out the Docs / Spec impact section (from the PR template). If you claim "None", reviewers should treat that as a strong assertion.

5. Linting, types, and tests

Before pushing:

npm run lint
npm run typecheck   # if defined
npm test            # in apps/api

In CI, we also run:

  • turbo lint
  • turbo build
  • API unit tests and (eventually) E2E against a fresh Supabase instance

6. Documentation obligations

  • If you change behavior — update spec/behavior.md.
  • If you change data model — update spec/architecture.md.
  • If you change developer workflow — update the relevant guide in apps/docs/app/guides/.
Warning

Out‑of‑date documentation is a real bug. When in doubt, fix the docs in the same PR as the implementation change.

CI enforcement:

  • PRs that change product code (API, packages, Supabase, or app shells) must also change apps/docs/ and/or spec/, or CI will fail.