PR Checklist

Required checks, branch rules, and commit conventions for pull requests

PR Checklist

Every pull request must pass a set of local checks before it is created. This page covers the required commands, branch naming rules, and commit conventions.

Pre-PR Checks

Run all four checks locally before pushing your branch. Every check must pass with zero errors.

1. Lint

npm run lint

Must complete with 0 errors. Warnings are acceptable but should be minimized.

2. Type Check

npx tsc --noEmit

Ensures all TypeScript types compile correctly without emitting output files.

3. Unit Tests

npm run test -- --run

All unit tests must pass. To run only unit tests:

npm run test -- --run "src/__tests__/unit/"

4. Production Build

npm run build

The Next.js production build must complete successfully. This catches issues that lint and type-check may miss (e.g., missing imports in server components, build-time errors).

Quick All-in-One Command

Run all checks in sequence. If any step fails, the chain stops:

npm run lint && npx tsc --noEmit && npm run test -- --run "src/__tests__/unit/"

The npm run build step is omitted from the one-liner since it takes longer. Run it separately after the quick checks pass.

Branch Naming

All work must be done on a feature branch. Branch names follow this convention:

Prefix	Usage	Example
feat/	New features	feat/toll-reconciliation
fix/	Bug fixes	fix/csv-date-parsing
refactor/	Code refactoring	refactor/kpi-calculations
chore/	Maintenance tasks	chore/update-dependencies
docs/	Documentation only	docs/api-routes
ci/	CI/CD changes	ci/playwright-setup

# Create and switch to a new branch
git checkout -b feat/my-feature

Commit Message Format

Use conventional commits:

type(scope): description

Type	When to Use
feat	New feature
fix	Bug fix
refactor	Code change that neither fixes a bug nor adds a feature
chore	Build, tooling, or dependency changes
docs	Documentation changes
test	Adding or updating tests
ci	CI/CD pipeline changes
style	Formatting, whitespace (no code logic change)

Examples:

feat(tolls): add SunPass CSV import support
fix(trips): correct timezone offset in date display
refactor(hooks): extract shared pagination logic
chore(deps): update Next.js to 15.1

Branch Protection Rules

These rules are enforced and have no exceptions:

Never push directly to main. All changes must go through a feature branch and pull request. This applies to every change, no matter how small.

• Never run git push origin main or git push --force origin main
• Never use --no-verify to bypass hooks when pushing to main
• Never force push to main under any circumstances
• Always create a feature branch first, push to it, then open a PR

Git Rules

• Do not add Co-Authored-By lines to commit messages
• Keep commit messages concise and descriptive
• Squash trivial fix-up commits before requesting review

Workflow Summary

# 1. Create feature branch
git checkout -b feat/my-feature

# 2. Make changes and commit
git add .
git commit -m "feat(scope): description"

# 3. Run all checks
npm run lint
npx tsc --noEmit
npm run test -- --run "src/__tests__/unit/"
npm run build

# 4. Fix any errors, re-commit

# 5. Push feature branch
git push origin feat/my-feature

# 6. Create PR to merge into main

What GitHub Actions Will Check

When you open a PR, the CI pipeline runs the same checks:

1. npm run lint — Lint errors fail the build
2. npx tsc --noEmit — Type errors fail the build
3. npm run test -- --run — Test failures fail the build
4. npm run build — Build errors fail the build
5. Playwright E2E tests — Run against the preview deployment

Running checks locally before pushing saves CI minutes and avoids failed builds.