# Contributing Guide

Thanks for contributing to car64.

## Workflow

- Create a branch from `main`:
  - `feature/<short-name>` for features
  - `fix/<short-name>` for bug fixes
  - `docs/<short-name>` for documentation updates
- Keep pull requests focused and small when possible.
- Write clear commit messages (Conventional Commit style is preferred).

## Development Setup

1. Install Flutter stable and run `flutter doctor`.
2. Copy `.env/flutter_defines.example.json` to `.env/flutter_defines.json`.
3. Fill in your own Supabase config values.
4. Run:

```bash
flutter pub get
flutter analyze
```

## Code Style

- Follow existing project style and naming patterns.
- Prefer small, explicit methods over deeply nested logic.
- Preserve backend contract names (`hotwheels`, RPC names, etc.) unless migration is intentional.

## Testing & Validation

Before opening a PR:

- Run `flutter analyze`
- Run available tests
- Manually test affected flows (scanner, collections, auth, storage upload)

## Pull Request Checklist

- [ ] Scope is clear and focused
- [ ] Analyzer passes
- [ ] User-facing strings are intentional and reviewed
- [ ] No secrets/config values were committed
- [ ] README/docs updated if behavior changed

## Commit Message Examples

Preferred format:

```text
type(scope): short summary
```

Common types used in this repository:

- `feat`: new feature
- `fix`: bug fix
- `perf`: performance improvement
- `docs`: documentation-only change
- `refactor`: code cleanup without behavior change
- `test`: tests added/updated
- `chore`: maintenance/tooling/config updates

Examples:

- `feat(scanner): add adaptive cooldown for repeated OCR misses`
- `fix(garage): prevent duplicate copy into target collection`
- `perf(collections): coalesce overlapping refresh requests`
- `docs(readme): add VS Code release build task usage`
- `refactor(auth): simplify session guard flow in AuthGate`
- `test(utils): cover scanner id extraction edge cases`
- `chore(vscode): add release build tasks for apk and appbundle`