docs(workflow): formalize gitflow process and templates

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
-- `develop`: integration
-- `feature/*`: features from `develop`
-- `release/*`: stabilization from `develop`
+- `main`: production branch
+- `develop`: integration branch
+- `feature/*`: new feature branches 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`).