178 lines
3.9 KiB
Markdown
178 lines
3.9 KiB
Markdown
# 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'
|
|
```
|