From f9329df64f01a0e6c4c1091ea03c540f77dd330f Mon Sep 17 00:00:00 2001 From: Alfredo Di Stasio Date: Tue, 10 Mar 2026 11:58:34 +0100 Subject: [PATCH] docs(workflow): formalize gitflow process and templates --- .github/ISSUE_TEMPLATE/bug_report.md | 35 ++++ .github/ISSUE_TEMPLATE/config.yml | 5 + .github/ISSUE_TEMPLATE/feature_request.md | 30 +++ .github/PULL_REQUEST_TEMPLATE.md | 26 +++ CHANGELOG.md | 25 +++ CONTRIBUTING.md | 225 ++++++++++++---------- README.md | 64 +++++- docker-compose.yml | 3 +- docs/workflow.md | 77 ++++++++ 9 files changed, 381 insertions(+), 109 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 CHANGELOG.md create mode 100644 docs/workflow.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..16901e3 --- /dev/null +++ b/.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. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..1ef92a1 --- /dev/null +++ b/.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. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..0db7bbe --- /dev/null +++ b/.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/-` +- Target milestone: diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..c5c389d --- /dev/null +++ b/.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. diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..ad0d338 --- /dev/null +++ b/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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 486126e..cece440 100644 --- a/CONTRIBUTING.md +++ b/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 -- `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/-` +- `release/..` +- `hotfix/-` -- `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 diff --git a/README.md b/README.md index bcaa0f0..e218ed7 100644 --- a/README.md +++ b/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`). diff --git a/docker-compose.yml b/docker-compose.yml index 5d722bc..c512ffb 100644 --- a/docker-compose.yml +++ b/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: diff --git a/docs/workflow.md b/docs/workflow.md new file mode 100644 index 0000000..5c8a1e2 --- /dev/null +++ b/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/- +``` + +Create `release/*`: + +```bash +git checkout develop +git pull origin develop +git checkout -b release/.. +``` + +Create `hotfix/*`: + +```bash +git checkout main +git pull origin main +git checkout -b hotfix/- +``` + +## 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.