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

35
.github/ISSUE_TEMPLATE/bug_report.md vendored Normal file
View File

@ -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.

5
.github/ISSUE_TEMPLATE/config.yml vendored Normal file
View File

@ -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.

30
.github/ISSUE_TEMPLATE/feature_request.md vendored Normal file
View File

@ -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:

26
.github/PULL_REQUEST_TEMPLATE.md vendored Normal file
View File

@ -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.

25
CHANGELOG.md Normal file
View File

@ -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.

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

64
README.md
View File

@ -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`).

3
docker-compose.yml
View File

@ -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:

77
docs/workflow.md Normal file
View File

@ -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.