Branching & Pull Requests
Branch Naming
Every branch follows this pattern:
<type>/<issue#>-<short-description>
| Type | When to use |
|---|---|
feat/ | New feature or functionality |
fix/ | Bug fix |
docs/ | Documentation changes |
chore/ | Tooling, CI, dependencies |
hotfix/ | Urgent production fix |
refactor/ | Code restructuring (no behavior change) |
Examples
feat/212-map-filter-ui
fix/215-cors-header
docs/update-contributing
chore/add-husky
hotfix/auth-redirect
Pull Request Rules
Keep PRs small
- Aim for under 400 lines changed. If your PR is bigger, split it up.
- Small PRs get reviewed faster and have fewer bugs.
- A reviewer should be able to understand your PR in 10-15 minutes.
One PR = one concern
Don't mix different types of work in one PR. For example:
- Don't fix a bug AND add a new feature in the same PR
- Don't refactor code AND change behavior in the same PR
- Don't update styles AND change API logic in the same PR
Branch off staging, merge to staging
staging
└── your-branch
All feature work targets staging. The main branch is production only.
Open draft PRs early
Open a draft PR on day 1 of your work. This lets the reviewer:
- See the direction you're heading
- Catch design issues early
- Give feedback before you've written 1000 lines
No long-lived branches
If your branch has been open for more than 5 days, it's probably too big. Break it up.
How to Split Big Features
If you need to build something large (e.g. a new page with API + UI + data), split it into sequential PRs:
Example: Building a map filter feature
| PR | Branch | What | Lines |
|---|---|---|---|
| 1 | feat/212-map-filter-types | TypeScript types and schema | ~50 |
| 2 | feat/212-map-filter-api | API route / tRPC procedure | ~100 |
| 3 | feat/212-map-filter-ui | React component | ~200 |
| 4 | feat/212-map-filter-integration | Wire everything together | ~100 |
Each PR merges to staging independently. Each is reviewable in 15 minutes.
Commit Messages
We use Conventional Commits. This is enforced by commitlint.
Format
<type>: <short description>
Types
| Type | Description |
|---|---|
feat | New feature |
fix | Bug fix |
docs | Documentation |
chore | Tooling, CI, maintenance |
refactor | Code change that doesn't fix a bug or add a feature |
style | Formatting, whitespace (no code change) |
test | Adding or updating tests |
Examples
feat: add map filter dropdown
fix: correct CORS header for mobile requests
docs: update contributing guidelines
chore: add husky pre-commit hooks
refactor: extract place parser to shared utils
Bad commit messages (will be rejected)
fixed stuff ← not conventional format
update ← too vague
WIP ← commit when it's ready, not before