Contributing

Branching Strategy

We use a staging-based flow — feature branches merge into staging for integration, then staging is promoted to main for production deployment.

Branches

• All feature/fix PRs target staging
• Only hotfix/* branches may target main directly
• Protected with required reviews and status checks

Branch Naming

Workflow

Normal flow:

1. Pick a GitHub Issue
2. Create feature branch from staging
3. Implement changes (with tests)
4. Open Pull Request targeting staging
5. Pass all quality gates
6. Get review approval
7. Merge to staging
8. (Optional) Trigger Deploy Preview from Actions tab
9. When ready, promote staging → main for production deploy

Hotfix flow:

1. Create hotfix/* branch from main
2. Implement minimal fix
3. Open Pull Request targeting main
4. Pass all quality gates + review
5. Merge to main → auto-deploys to production
6. Cherry-pick or merge fix back into staging

Commit Conventions

We follow Conventional Commits for clear, automated changelogs.

Format

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Types

Scope

Use the package name for monorepo changes:

• feat(web): - Frontend changes
• fix(api): - Backend changes
• docs(ui): - UI package documentation
• chore(config): - Config package maintenance

Breaking Changes

Add ! after the type or include BREAKING CHANGE: in the footer:

feat(api)!: redesign authentication endpoints

BREAKING CHANGE: /auth/login now requires email instead of username

Examples

feat(web): add user authentication flow
fix(api): resolve database connection timeout
docs: update README with installation steps
test(ui): add Button component tests
chore: update dependencies
ci: add coverage reporting to pipeline

Pull Requests

Before Opening a PR

• Branch is up-to-date with staging (or main for hotfixes)
• All tests pass locally (bun run test)
• Linting passes (bun lint)
• Types check (bun typecheck)
• Commit messages follow conventions

PR Title

Use Conventional Commits format for the PR title (used for squash merge):

feat(web): add user dashboard
fix(api): resolve timeout on large queries

PR Description

Include:

• Summary of changes
• Link to related issue
• Testing performed
• Screenshots (for UI changes)

Quality Gates

All PRs must pass before merge:

After Merge

Merge to staging:

• CI runs on the push to staging
• No automatic deployment — use the Deploy Preview GitHub Action to create on-demand preview URLs

Merge to main:

• Vercel auto-deploys both web and API to production
• If something breaks, roll back via the Vercel dashboard (Deployments > Promote previous). See the Deployment Guide for details.

Branch Protection

main branch:

• Required pull request reviews (1 minimum)
• Required status checks (CI must pass)
• Dismiss stale approvals on new commits
• Require conversation resolution
• No direct pushes
• Only hotfix/* and staging merges allowed

staging branch:

• Required status checks (CI must pass)
• No direct pushes

Labels

Priority

Size

Type

Issue Templates

When creating issues, use the provided templates:

• Bug Report: For reporting bugs with reproduction steps
• Feature Request: For proposing new features

Documentation (MDX)

Documentation uses Fumadocs with MDX format. All docs live in the docs/ folder.

Creating Documentation Files

Files must be .mdx with frontmatter:

---
title: Page Title
description: Brief description for SEO and previews
---

Content here...

Folder Structure

docs/
├── index.mdx           # Home page
├── getting-started.mdx # Main docs
├── meta.json           # Navigation order
├── architecture/       # Architecture documentation
│   ├── meta.json
│   ├── index.mdx
│   └── *.mdx
├── processes/          # Development processes
│   ├── meta.json
│   ├── index.mdx
│   └── *.mdx
└── standards/          # Coding standards & best practices
    ├── meta.json
    └── *.mdx

Adding New Pages

1. Create .mdx file with frontmatter
2. Add filename (without extension) to meta.json in the pages array
3. Add an entry to the section's index.mdx page (with link and one-line description)
4. Run bun docs to preview

Glossary review: When updating architecture documentation (docs/architecture/), review the ubiquitous language glossary for any terms that need adding or updating.

Removing or Deprecating Pages

1. Add a > **Deprecated** callout at the top of the file
2. Remove the filename from meta.json (hides from sidebar)
3. Remove the entry from the section's index.mdx
4. Keep the file on disk for historical reference

Special Characters in MDX

Escape < as < in prose text to avoid JSX parsing errors (e.g., <50KB instead of <50KB). Inside fenced code blocks (```), always use raw < — escaping is not needed and renders as literal < text.

Heading Hierarchy

Do not use # Title as the first content line. Fumadocs renders the frontmatter title as the page H1 automatically. Adding # Title creates a duplicate H1 (bad for accessibility and SEO). Start your content with ## headings or prose text.

Internal Links

Use relative paths for all internal documentation links:

• Same directory: ./getting-started
• Parent directory: ../guides/authentication
• Never use absolute paths like /docs/guides/authentication

Developer Tools

Re-recording the Demo GIF

The README demo GIF is generated from a Playwright recording script. To re-record:

Prerequisites:

• bun dev running at http://localhost:3000 (or APP_URL)
• Database seeded with representative data (multiple orgs, different roles)
• ffmpeg installed (brew install ffmpeg / apt install ffmpeg)
• Playwright installed (bun add -D @playwright/test && bunx playwright install chromium)

Steps:

bun run scripts/recordDemo.ts

The script records a .webm video, converts it to GIF via ffmpeg, and saves to docs/assets/demo.gif. Keep the recording under 5MB -- if too large, reduce the flow to fewer steps or lower the resolution.

Getting Help

• Check existing issues before creating new ones
• Use discussions for questions
• Tag maintainers for urgent issues