Contributing to HoopScout v2

HoopScout uses GitFlow and a pragmatic, production-minded workflow.

Branch Roles

main: production-only, always releasable
develop: integration branch
feature/*: feature branches from develop
release/*: release hardening branches from develop
hotfix/*: urgent production fixes from main

Branch Naming

Use lowercase kebab-case:

feature/<scope>-<short-description>
release/<major>.<minor>.<patch>
hotfix/<scope>-<short-description>

Examples:

feature/hoopscout-v2-static-architecture
feature/v2-snapshot-import-command
release/2.0.0
hotfix/nginx-proxy-timeout

v2 Development Runtime

The v2 default runtime is intentionally simple:

web
postgres
nginx

No Redis/Celery runtime services in the default v2 foundation.

Start dev stack

cp .env.example .env
docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build

Start release-style stack

docker compose -f docker-compose.yml -f docker-compose.release.yml up -d --build

Verify release topology assumptions

docker compose -f docker-compose.yml -f docker-compose.release.yml config
./scripts/verify_release_topology.sh

Day-to-Day Feature Workflow

Sync develop

git checkout develop
git pull origin develop

Create feature branch

git checkout -b feature/your-feature-name

Implement with focused commits and tests.
Open PR: feature/* -> develop.

Running Tests (v2)

Runtime images are intentionally lean and may not ship pytest. Use the development compose stack and install dev dependencies before running tests:

docker compose -f docker-compose.yml -f docker-compose.dev.yml run --rm web sh -lc "export PYTHONUSERBASE=/tmp/pyuser && python -m pip install --user -r requirements/dev.txt && python -m pytest -q"

PR Checklist

Target branch is correct
Scope is focused (no unrelated refactor)
Runtime still starts with docker compose
Tests updated/passing for changed scope
Docs updated (README.md, .env.example, this file) when config/runtime changes
No secrets committed

v2 Foundation Rules

Prefer management commands over distributed orchestration unless clearly justified.
Keep PostgreSQL as source of truth.
Keep snapshot storage file-based and volume-backed.
Do not introduce MongoDB or Elasticsearch as source of truth.
Keep legacy provider/Celery sync code isolated behind LEGACY_PROVIDER_STACK_ENABLED=1.
Keep runtime/docs consistency aligned with docs/runtime-consistency-checklist.md.

Repository Bootstrap Commands

If develop is missing in a clone:

git checkout main
git pull origin main
git checkout -b develop
git push -u origin develop

2.8 KiB Raw Blame History