docs(workflow): formalize gitflow process and templates

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,35 @@
+---
+name: Bug report
+about: Report a defect affecting behavior or reliability
+title: "[Bug] "
+labels: bug
+assignees: ""
+---
+
+## Description
+
+What is wrong?
+
+## Steps to Reproduce
+
+1.
+2.
+3.
+
+## Expected Behavior
+
+What should happen?
+
+## Actual Behavior
+
+What happens instead?
+
+## Environment
+
+- Branch:
+- Commit:
+- Docker command used:
+
+## Logs / Screenshots
+
+Add relevant logs or screenshots.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Contribution Guidelines
+    url: ./CONTRIBUTING.md
+    about: Read branch rules and PR checklist before opening work items.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,30 @@
+---
+name: Feature request
+about: Propose a new capability aligned with product milestones
+title: "[Feature] "
+labels: enhancement
+assignees: ""
+---
+
+## Problem
+
+What user or business problem are we solving?
+
+## Proposed Solution
+
+Describe the minimum viable implementation.
+
+## Scope
+
+- In scope:
+- Out of scope:
+
+## Acceptance Criteria
+
+- [ ]
+- [ ]
+
+## GitFlow Plan
+
+- Branch suggestion: `feature/<scope>-<short-description>`
+- Target milestone:

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,26 @@
+## Summary
+
+Describe what changed and why.
+
+## Branch and Target
+
+- Source branch: `feature/*` / `release/*` / `hotfix/*`
+- Target branch: `develop` / `main`
+
+## Checklist
+
+- [ ] Scope is focused and avoids unrelated refactors
+- [ ] Docker stack runs (`docker compose up -d`)
+- [ ] Tests are passing
+- [ ] Migrations included (if needed)
+- [ ] Docs updated (if needed)
+- [ ] Changelog updated under `Unreleased`
+- [ ] No secrets committed
+
+## Testing
+
+List commands and key outputs.
+
+## Risk and Rollback
+
+Briefly note deployment risk and rollback approach.

CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format follows a lightweight Keep a Changelog style.
+
+## [Unreleased]
+
+### Added
+
+- Repository GitFlow workflow guide and templates.
+
+### Changed
+
+- Clarified branch naming and release/hotfix operations in contributor docs.
+
+### Fixed
+
+- N/A
+
+## [0.0.0] - 2026-03-10
+
+### Added
+
+- Initial HoopScout project foundation and phased implementation baseline.

CONTRIBUTING.md

@@ -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
+## Branch Roles
-- `develop`: integration branch
-- `feature/*`: implementation branches from `develop`
-- `release/*`: release hardening branches from `develop`
-- `hotfix/*`: urgent production fixes from `main`
 
-## 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`
+Use lowercase kebab-case.
-- `feature/provider-sportradar-adapter`
-- `feature/scouting-watchlist-notes`
 
-Release branches:
+- `feature/<scope>-<short-description>`
+- `release/<major>.<minor>.<patch>`
+- `hotfix/<scope>-<short-description>`
 
-- `release/0.9.0-beta`
+Examples:
-- `release/1.0.0`
 
-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`
+## Day-to-Day Feature Workflow
-- `hotfix/nginx-healthcheck-timeout`
 
-## Practical Workflow
+1. Sync `develop`.
-
-1. Sync base branch:
 
 ```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.
+3. Implement, test, commit in small logical steps.
-4. Open PR into `develop`.
-5. Require passing tests/checks and review before merge.
 
-For release:
+4. Rebase or merge latest `develop` before PR if needed.
 
-1. Create `release/*` from `develop`.
+```bash
-2. Stabilize, run regression tests, update docs/versioning.
+git checkout develop
-3. Merge `release/*` into `main` and back into `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`.
+## Recommended Release Workflow
-2. Patch, test, merge to `main` and `develop`.
+
+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

README.md

@@ -42,11 +42,14 @@ A minimal read-only API is included as a secondary integration surface.
 │   └── users/
 ├── config/
 │   └── settings/
+├── docs/
 ├── nginx/
 ├── requirements/
 ├── static/
 ├── templates/
 ├── tests/
+├── .github/
+├── CHANGELOG.md
 ├── docker-compose.yml
 ├── Dockerfile
 └── entrypoint.sh
@@ -99,7 +102,8 @@ docker compose exec web python manage.py createsuperuser
 - `postgres_data`: PostgreSQL persistent database
 - `static_data`: collected static assets
 - `media_data`: user/provider media artifacts
-- `runtime_data`: persistent runtime files (e.g., celery beat schedule, redis data)
+- `runtime_data`: app runtime files (e.g., celery beat schedule)
+- `redis_data`: Redis persistence (`/data` for RDB/AOF files)
 
 This keeps persistent state outside container lifecycles.
 
@@ -172,14 +176,58 @@ trigger_full_sync.delay(provider_namespace="mvp_demo")
 - Structured error records: `IngestionError`
 - Provider entity mappings + diagnostic payload snippets: `ExternalMapping`
 
-## GitFlow Reference
+## GitFlow Workflow
 
-HoopScout uses strict GitFlow:
+GitFlow is required in this repository:
 
-- `main`: production-ready
+- `main`: production branch
-- `develop`: integration
+- `develop`: integration branch
-- `feature/*`: features from `develop`
+- `feature/*`: new feature branches from `develop`
-- `release/*`: stabilization from `develop`
+- `release/*`: release hardening branches from `develop`
 - `hotfix/*`: urgent production fixes from `main`
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for practical examples and milestone planning.
+Read full details in [CONTRIBUTING.md](CONTRIBUTING.md) and [docs/workflow.md](docs/workflow.md).
+
+### Repository Bootstrap Commands
+
+Run these from the current `main` branch to initialize local GitFlow usage:
+
+```bash
+git checkout main
+git pull origin main
+git checkout -b develop
+git push -u origin develop
+```
+
+Start a feature branch:
+
+```bash
+git checkout develop
+git pull origin develop
+git checkout -b feature/player-search-tuning
+```
+
+Start a release branch:
+
+```bash
+git checkout develop
+git pull origin develop
+git checkout -b release/0.1.0
+```
+
+Start a hotfix branch:
+
+```bash
+git checkout main
+git pull origin main
+git checkout -b hotfix/fix-redis-persistence
+```
+
+## Release Notes / Changelog Convention
+
+- Use [CHANGELOG.md](CHANGELOG.md) with an `Unreleased` section.
+- For each merged PR, add short entries under:
+  - `Added`
+  - `Changed`
+  - `Fixed`
+- On release, move `Unreleased` items to a dated version section (`[x.y.z] - YYYY-MM-DD`).

docker-compose.yml

@@ -104,7 +104,7 @@ services:
     image: redis:7-alpine
     command: redis-server --save 60 1 --loglevel warning
     volumes:
-      - runtime_data:/data
+      - redis_data:/data
     healthcheck:
       test: ["CMD", "redis-cli", "ping"]
       interval: 10s
@@ -117,3 +117,4 @@ volumes:
   static_data:
   media_data:
   runtime_data:
+  redis_data:

docs/workflow.md

@@ -0,0 +1,77 @@
+# GitFlow Workflow Notes
+
+This document is the operational reference for branch and release flow in HoopScout.
+
+## Branch Types
+
+- `main`: production
+- `develop`: integration
+- `feature/*`: new work from `develop`
+- `release/*`: release preparation from `develop`
+- `hotfix/*`: urgent production fixes from `main`
+
+## Branch Start Commands
+
+Create `develop` from current `main`:
+
+```bash
+git checkout main
+git pull origin main
+git checkout -b develop
+git push -u origin develop
+```
+
+Create `feature/*`:
+
+```bash
+git checkout develop
+git pull origin develop
+git checkout -b feature/<scope>-<short-description>
+```
+
+Create `release/*`:
+
+```bash
+git checkout develop
+git pull origin develop
+git checkout -b release/<major>.<minor>.<patch>
+```
+
+Create `hotfix/*`:
+
+```bash
+git checkout main
+git pull origin main
+git checkout -b hotfix/<scope>-<short-description>
+```
+
+## Release Flow
+
+1. Branch `release/x.y.z` from `develop`.
+2. Freeze feature work on release branch (only bugfix/docs/changelog).
+3. Validate in Docker and test suite.
+4. Merge release branch into `main`.
+5. Tag `vX.Y.Z` on `main`.
+6. Merge release branch back into `develop`.
+
+## Hotfix Flow
+
+1. Branch `hotfix/*` from `main`.
+2. Apply minimum safe fix and tests.
+3. Merge hotfix into `main`.
+4. Tag patch release (`vX.Y.Z`).
+5. Merge hotfix into `develop`.
+
+## Milestone-Oriented Branching Recommendation
+
+Recommended sequence for planning feature branches:
+
+1. Domain and indexing stability
+2. Search/filter performance
+3. Scouting UX workflows
+4. Provider adapter breadth
+5. Ingestion observability
+6. API hardening
+7. Security and rate-limit tuning
+
+Keep milestones in issues/boards; use branches only for implementation slices.