110 lines
2.8 KiB
Markdown
110 lines
2.8 KiB
Markdown
# 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
|
|
```
|
|
|
|
### Verify release topology assumptions
|
|
|
|
```bash
|
|
docker compose -f docker-compose.yml -f docker-compose.release.yml config
|
|
./scripts/verify_release_topology.sh
|
|
```
|
|
|
|
## 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.
|
|
- 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:
|
|
|
|
```bash
|
|
git checkout main
|
|
git pull origin main
|
|
git checkout -b develop
|
|
git push -u origin develop
|
|
```
|