> ## Documentation Index
> Fetch the complete documentation index at: https://dhanurgo.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
npm run lint
```

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

### 2. Type Check

```bash theme={null}
npx tsc --noEmit
```

Ensures all TypeScript types compile correctly without emitting output files.

### 3. Unit Tests

```bash theme={null}
npm run test -- --run
```

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

```bash theme={null}
npm run test -- --run "src/__tests__/unit/"
```

### 4. Production Build

```bash theme={null}
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:

```bash theme={null}
npm run lint && npx tsc --noEmit && npm run test -- --run "src/__tests__/unit/"
```

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

## 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`       |

```bash theme={null}
# 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**:

<Warning>
  **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.
</Warning>

* **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

```bash theme={null}
# 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.