bisco/hoopscout
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(workflow): formalize gitflow process and templates

Browse Source
This commit is contained in:
Alfredo Di Stasio
2026-03-10 11:58:34 +01:00
parent 30595d0d89
commit f9329df64f
9 changed files with 381 additions and 109 deletions
Download Patch File Download Diff File Expand all files Collapse all files

225
CONTRIBUTING.md
View File

@ -1,60 +1,152 @@
# Contributing to HoopScout
## GitFlow Policy (Required)
This repository follows a pragmatic GitFlow model.
The goal is predictable releases with low process overhead.
- `main`: production branch
- `develop`: integration branch
- `feature/*`: implementation branches from `develop`
- `release/*`: release hardening branches from `develop`
- `hotfix/*`: urgent production fixes from `main`
## Branch Roles
## Branch Naming Examples
- `main`: production-only, always releasable
- `develop`: integration branch for upcoming release
- `feature/*`: feature work, branched from `develop`, merged into `develop`
- `release/*`: stabilization branch, branched from `develop`, merged into `main` and back into `develop`
- `hotfix/*`: urgent production fixes, branched from `main`, merged into `main` and back into `develop`
Feature branches:
## Branch Naming Convention
- `feature/player-search-performance`
- `feature/provider-sportradar-adapter`
- `feature/scouting-watchlist-notes`
Use lowercase kebab-case.
Release branches:
- `feature/<scope>-<short-description>`
- `release/<major>.<minor>.<patch>`
- `hotfix/<scope>-<short-description>`
- `release/0.9.0-beta`
- `release/1.0.0`
Examples:
Hotfix branches:
- `feature/search-age-height-filters`
- `feature/providers-mvp-retry-logic`
- `release/0.2.0`
- `hotfix/redis-volume-permissions`
- `hotfix/fix-ingestion-run-crash`
- `hotfix/nginx-healthcheck-timeout`
## Day-to-Day Feature Workflow
## Practical Workflow
1. Sync base branch:
1. Sync `develop`.
```bash
git checkout develop
git pull
git pull origin develop
```
2. Create feature branch:
2. Create 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.
3. Implement, test, commit in small logical steps.
For release:
4. Rebase or merge latest `develop` before PR if needed.
1. Create `release/*` from `develop`.
2. Stabilize, run regression tests, update docs/versioning.
3. Merge `release/*` into `main` and back into `develop`.
```bash
git checkout develop
git pull origin develop
git checkout feature/your-feature-name
git rebase develop
```
For production urgent fix:
5. Open PR: `feature/*` -> `develop`.
1. Create `hotfix/*` from `main`.
2. Patch, test, merge to `main` and `develop`.
## Recommended Release Workflow
1. Create release branch from `develop`.
```bash
git checkout develop
git pull origin develop
git checkout -b release/0.1.0
```
2. On `release/*` allow only:
- bug fixes
- docs/changelog updates
- release metadata/version updates
3. Validate release candidate in Docker.
```bash
docker compose up -d --build
docker compose run --rm web sh -lc 'pip install -r requirements/dev.txt && pytest -q'
```
4. Merge `release/*` into `main`.
5. Tag release on `main` (`v0.1.0`).
6. Merge the same `release/*` back into `develop`.
7. Delete release branch after both merges.
## Recommended Hotfix Workflow
1. Create hotfix branch from `main`.
```bash
git checkout main
git pull origin main
git checkout -b hotfix/your-hotfix-name
```
2. Implement minimal fix and tests.
3. Open PR: `hotfix/*` -> `main`.
4. After merge to `main`, back-merge to `develop`.
5. Tag patch release (`vX.Y.Z`).
## Pull Request Checklist
Before requesting review, confirm:
- [ ] Branch target is correct (`develop`, `main`, or release back-merge)
- [ ] Scope is focused (no unrelated refactors)
- [ ] Docker stack still starts (`docker compose up -d`)
- [ ] Tests updated and passing
- [ ] Migrations included if models changed
- [ ] Docs updated (`README`, `CONTRIBUTING`, `.env.example`) when needed
- [ ] No secrets or credentials committed
- [ ] Changelog entry added under `Unreleased`
## Issue and Feature Templates
Use repository templates in `.github/ISSUE_TEMPLATE/`:
- `bug_report.md`
- `feature_request.md`
Use `.github/PULL_REQUEST_TEMPLATE.md` for PR descriptions.
## Changelog / Release Note Convention
- Single changelog file: `CHANGELOG.md`
- Keep `Unreleased` at top
- Categorize entries under:
- `Added`
- `Changed`
- `Fixed`
- Release format:
- `## [0.1.0] - 2026-03-10`
## Repository Bootstrap Commands
Maintainers should run these once to start GitFlow from current `main`:
```bash
git checkout main
git pull origin main
git checkout -b develop
git push -u origin develop
```
Then start regular feature work:
```bash
git checkout develop
git pull origin develop
git checkout -b feature/first-team-task
```
## Local Development Setup
@ -70,7 +162,7 @@ docker compose exec web python manage.py migrate
docker compose exec web python manage.py createsuperuser
```
## Testing Guidelines
## Testing Commands
Run full suite:
@ -83,70 +175,3 @@ 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