phase8: expand test coverage and refine docs with gitflow milestones

CONTRIBUTING.md

@@ -1,46 +1,152 @@
 # Contributing to HoopScout
 
-## Branching Model (GitFlow Required)
+## GitFlow Policy (Required)
 
-- `main`: production-ready releases only
-- `develop`: integration branch for completed features
-- `feature/*`: feature development branches from `develop`
+- `main`: production branch
+- `develop`: integration branch
+- `feature/*`: implementation branches from `develop`
 - `release/*`: release hardening branches from `develop`
 - `hotfix/*`: urgent production fixes from `main`
 
-## Workflow
+## Branch Naming Examples
 
-1. Create branch from the correct base:
-   - `feature/*` from `develop`
-   - `release/*` from `develop`
-   - `hotfix/*` from `main`
-2. Keep branch scope small and focused.
-3. Open PR into the proper target branch.
-4. Require passing CI checks and at least one review.
-5. Squash or rebase merge according to repository policy.
+Feature branches:
 
-## Local Development
+- `feature/player-search-performance`
+- `feature/provider-sportradar-adapter`
+- `feature/scouting-watchlist-notes`
 
-1. `cp .env.example .env`
-2. `docker compose up --build`
-3. `docker compose exec web python manage.py migrate`
-4. `docker compose exec web python manage.py createsuperuser`
+Release branches:
 
-## Testing
+- `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
-docker compose exec web pytest
+git checkout develop
+git pull
 ```
 
-## Commit Guidance
+2. Create feature branch:
 
-- Use clear commit messages with intent and scope.
-- Avoid mixing refactors with feature behavior changes.
-- Include migration files when model changes are introduced.
+```bash
+git checkout -b feature/your-feature-name
+```
 
-## Definition of Done (MVP)
+3. Implement and test in Docker.
+4. Open PR into `develop`.
+5. Require passing tests/checks and review before merge.
 
-- Feature works in Dockerized environment.
-- Tests added/updated for behavior change.
-- Documentation updated when commands, config, or workflows change.
-- No secrets committed.
+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