hoopscout/CONTRIBUTING.md

Contributing to HoopScout

This repository follows a pragmatic GitFlow model. The goal is predictable releases with low process overhead.

Branch Roles

• 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

Branch Naming Convention

Use lowercase kebab-case.

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

Examples:

• feature/search-age-height-filters
• feature/providers-mvp-retry-logic
• release/0.2.0
• hotfix/redis-volume-permissions

Day-to-Day Feature Workflow

1. Sync develop.

git checkout develop
git pull origin develop

2. Create branch.

git checkout -b feature/your-feature-name

3. Implement, test, commit in small logical steps.

4. Rebase or merge latest develop before PR if needed.

git checkout develop
git pull origin develop
git checkout feature/your-feature-name
git rebase develop

5. Open PR: feature/* -> develop.

Recommended Release Workflow

1. Create release branch from develop.

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.

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.

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:

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

Then start regular feature work:

git checkout develop
git pull origin develop
git checkout -b feature/first-team-task

Local Development Setup

cp .env.example .env
docker compose up --build

If needed:

docker compose exec web python manage.py migrate
docker compose exec web python manage.py createsuperuser

Testing Commands

Run full suite:

docker compose run --rm web sh -lc 'pip install -r requirements/dev.txt && pytest -q'

Run targeted modules while developing:

docker compose run --rm web sh -lc 'pip install -r requirements/dev.txt && pytest -q tests/test_players_views.py'