Pull Requests

How code lands.

Branching#

• main is production (currently monorepo is the active integration branch — will rename to main after first prod cutover).
• Feature branches off main: feature/<short-description>, fix/<short-description>, chore/<short-description>.
• Long-lived migration branches use the slice naming: slice-3-workspace-carve.
• Delete the branch after merge.

Commits#

• One commit per logical change. Squash noise locally before opening the PR.
• Commit message format:

<subject — imperative mood, <72 chars>>

<wrap body at 80 chars. Explain why, not what — the diff shows what.
Reference the PR / issue. Document any decisions or trade-offs taken.>

Co-Authored-By: ...

• For multi-phase work (like the migration slices), each phase gets its own commit with a prefix: Slice 3 Phase A: …. Makes the history readable.

PR template#

## What
One paragraph: the user-visible change.

## Why
The motivation — what was broken or what's being unlocked.

## How
Brief overview of the approach. Call out any non-obvious choices.

## Testing
- [ ] `pnpm run type:check` clean
- [ ] `pnpm --filter @matters/workspace type:check` clean
- [ ] `pnpm --filter @matters/webdocs type:check` clean
- [ ] Manual smoke test (describe).
- [ ] Updated docs in `apps/webdocs/` if the change is user-visible.

## Risk
What could go wrong? How would we know? What's the rollback?

Review#

• One approval required to merge to main (currently lighter — bring in a second reviewer for anything touching auth, RBAC, money, or PII).
• Reviewers focus on:
  1. Correctness — does it do the thing?
  2. Safety — auth, RBAC, input validation, rate limits, audit logging.
  3. Style — see Code Style.
  4. Docs — does it update the relevant page in apps/webdocs/?
• Author addresses every comment (resolve or push back). Reviewer re-approves after follow-up commits.

CI gates#

.github/workflows/ci.yml runs on every push and PR:

1. Install (frozen lockfile).
2. Type-check root + workspace + webdocs.
3. Lint (currently continue-on-error: true).
4. Build workspace + webdocs.

Merging without green CI is allowed today but discouraged. The lint gate will go to continue-on-error: false once the existing lint debt is paid down — track in PROD_CHECKLIST.md § 4.

Decisions worth documenting#

If you make a non-obvious choice (e.g. "we picked Fumadocs over Nextra because X"), put it either:

• In the relevant apps/webdocs/ page if it affects future contributors.
• In an ADR (architectural decision record) — directory TBD; for now, a top-comment block in the file the decision lives in.

What requires a security review#

Open a PR but tag @security and wait for explicit approval before merging:

• Anything touching packages/auth/src/email-allowlist.ts.
• Anything touching lib/auth/rbac-shared.ts (roles, permissions).
• New /api/webhooks/* routes.
• Changes to proxy.ts (either root or workspace).
• New direct process.env.* reads (route them through env).

When in doubt#

Ask. The 30-second Slack message is cheaper than a bad merge.