# Contributing to HoopScout

## GitFlow Policy (Required)

- `main`: production branch
- `develop`: integration branch
- `feature/*`: implementation branches from `develop`
- `release/*`: release hardening branches from `develop`
- `hotfix/*`: urgent production fixes from `main`

## Branch Naming Examples

Feature branches:

- `feature/player-search-performance`
- `feature/provider-sportradar-adapter`
- `feature/scouting-watchlist-notes`

Release branches:

- `release/0.9.0-beta`
- `release/1.0.0`

Hotfix branches:

- `hotfix/fix-ingestion-run-crash`
- `hotfix/nginx-healthcheck-timeout`

## Practical Workflow

1. Sync base branch:

```bash
git checkout develop
git pull
```

2. Create feature branch:

```bash
git checkout -b feature/your-feature-name
```

3. Implement and test in Docker.
4. Open PR into `develop`.
5. Require passing tests/checks and review before merge.

For release:

1. Create `release/*` from `develop`.
2. Stabilize, run regression tests, update docs/versioning.
3. Merge `release/*` into `main` and back into `develop`.

For production urgent fix:

1. Create `hotfix/*` from `main`.
2. Patch, test, merge to `main` and `develop`.

## Local Development Setup

```bash
cp .env.example .env
docker compose up --build
```

If needed:

```bash
docker compose exec web python manage.py migrate
docker compose exec web python manage.py createsuperuser
```

## Testing Guidelines

Run full suite:

```bash
docker compose run --rm web sh -lc 'pip install -r requirements/dev.txt && pytest -q'
```

Run targeted modules while developing:

```bash
docker compose run --rm web sh -lc 'pip install -r requirements/dev.txt && pytest -q tests/test_players_views.py'
```

## Migration Guidelines

When schema changes are made:

1. Create migrations.
2. Review migration SQL implications.
3. Commit migration files with model changes.

Commands:

```bash
docker compose exec web python manage.py makemigrations
docker compose exec web python manage.py migrate
```

## Ingestion Development Notes

- Keep provider-specific code inside `apps/providers/*`.
- Keep orchestration and logging in `apps/ingestion/*`.
- Preserve idempotency (`update_or_create`, stable mappings).
- Store raw payloads only in designated diagnostic fields.

## Suggested Milestones (GitFlow-Aligned)

1. `M1 Infrastructure Foundation`
   - Container/runtime hardening
   - settings/security baseline
   - CI test pipeline
2. `M2 Domain + Search Core`
   - normalized schema
   - HTMX search flow
   - pagination/sorting/filter correctness
3. `M3 Scouting Productivity`
   - saved searches/watchlist UX
   - auth-protected workflows
4. `M4 Ingestion Reliability`
   - provider adapters
   - ingestion retries/rate-limit handling
   - admin operations
5. `M5 Integration Surface`
   - read-only API stabilization
   - docs and onboarding hardening
6. `M6 Release Hardening`
   - performance pass
   - observability and failure drills
   - release candidate QA

## Recommended Feature Branch Development Order

1. `feature/domain-stability-and-indexes`
2. `feature/search-query-optimization`
3. `feature/scouting-ux-polish`
4. `feature/provider-adapter-expansion`
5. `feature/ingestion-observability`
6. `feature/api-readonly-improvements`
7. `feature/security-and-rate-limit-tuning`

This order prioritizes core data correctness first, then user value, then integration breadth.

## Definition of Done

- Runs correctly in Docker
- Tests added/updated for behavior changes
- Migrations included when schema changes occur
- Docs updated (`README`, `CONTRIBUTING`, `.env.example`) when workflows/config change
- No secrets committed