# GitFlow Workflow Notes

This document is the operational reference for branch and release flow in HoopScout.

## Branch Types

- `main`: production
- `develop`: integration
- `feature/*`: new work from `develop`
- `release/*`: release preparation from `develop`
- `hotfix/*`: urgent production fixes from `main`

## Branch Start Commands

Create `develop` from current `main`:

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

Create `feature/*`:

```bash
git checkout develop
git pull origin develop
git checkout -b feature/<scope>-<short-description>
```

Create `release/*`:

```bash
git checkout develop
git pull origin develop
git checkout -b release/<major>.<minor>.<patch>
```

Create `hotfix/*`:

```bash
git checkout main
git pull origin main
git checkout -b hotfix/<scope>-<short-description>
```

## Release Flow

1. Branch `release/x.y.z` from `develop`.
2. Freeze feature work on release branch (only bugfix/docs/changelog).
3. Validate in Docker and test suite.
4. Merge release branch into `main`.
5. Tag `vX.Y.Z` on `main`.
6. Merge release branch back into `develop`.

## Hotfix Flow

1. Branch `hotfix/*` from `main`.
2. Apply minimum safe fix and tests.
3. Merge hotfix into `main`.
4. Tag patch release (`vX.Y.Z`).
5. Merge hotfix into `develop`.

## Milestone-Oriented Branching Recommendation

Recommended sequence for planning feature branches:

1. Domain and indexing stability
2. Search/filter performance
3. Scouting UX workflows
4. Provider adapter breadth
5. Ingestion observability
6. API hardening
7. Security and rate-limit tuning

Keep milestones in issues/boards; use branches only for implementation slices.