Contributing

Branching

See Branching Strategy for the full GitFlow model.

Short version:

All feature work branches from develop
PRs flow: feature/* → develop → staging → main
Hotfixes branch from main and PR to both main + develop

# Start a new feature
git checkout develop && git pull origin develop
git checkout -b feature/my-feature

Commit Messages

Follow Conventional Commits:

<type>(<scope>): <short summary>

Type	When to use
`feat`	New feature or page
`fix`	Bug fix
`chore`	Tooling, deps, CI changes
`docs`	Documentation only
`style`	Formatting, CSS changes
`refactor`	Code restructure (no behavior change)
`test`	Adding or fixing tests
`ci`	CI/CD changes
`perf`	Performance improvements

Examples:

feat(www): add speaking services grid
fix(api): handle missing RESEND_API_KEY gracefully
chore(deps): update next to 14.3.0
docs(governance): add branching strategy

Pull Requests

Title must follow Conventional Commits format
Link to relevant GitHub issue (if one exists)
All CI checks must pass before merge
Squash-merge preferred for feature branches
Vercel preview deploy must be functional

Environment Setup

# Requires pnpm 9+
corepack enable
pnpm install

# Copy env template
cp .env.example .env.local
# Fill in required values (see /reference/env-registry/)

pnpm dev         # runs all apps in parallel
pnpm dev:www     # main site only (port 3000)
pnpm dev:api     # api only (port 3001)

CI Checks

Every PR runs:

Lint — ESLint + Prettier
Type check — tsc --noEmit
Unit tests — Jest + React Testing Library
Security audit — pnpm audit --audit-level=high
Build — full production build

Merges to staging additionally run:

E2E tests — Playwright
Lighthouse audit — all scores must be ≥ 90

Code Style

TypeScript everywhere — no .js files in apps/
Tailwind CSS for all styling — no inline styles, no CSS modules
Server Components by default — "use client" only for interactive islands
Named exports only — no default exports from component files
Zod for all runtime validation (forms, API responses, env vars)

Questions?

Open a GitHub Discussion or reach out to the lead engineer (Jesse Lucus / VLN Security).