# 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

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

### Start release-style stack

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

## Day-to-Day Feature Workflow

1. Sync `develop`

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

2. Create feature branch

```bash
git checkout -b feature/your-feature-name
```

3. Implement with focused commits and tests.
4. 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:

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

## Repository Bootstrap Commands

If `develop` is missing in a clone:

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