153 lines
3.5 KiB
Markdown
153 lines
3.5 KiB
Markdown
# 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
|