hoopscout/CONTRIBUTING.md

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:

git checkout develop
git pull

2. Create feature branch:

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

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

If needed:

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

Testing Guidelines

Run full suite:

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

Run targeted modules while developing:

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:

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