# 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`.

```bash
git checkout develop
git pull origin develop
```

2. Create branch.

```bash
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.

```bash
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`.

```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

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

If needed:

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

## Testing Commands

Run full suite:

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

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'
```