# Branch Management Workflow

**Document status:** Active reference
**Date:** 2026-06-11

## Branch Naming Convention

Branches use `<type>/<short-description>`:

| Prefix | Purpose | Examples |
|--------|---------|---------|
| `feat/` | New feature | `feat/file-transfer`, `feat/poke-notifications` |
| `fix/`  | Bug fix | `fix/ios-audio-playback-capture`, `fix/cross-platform-audio-route` |
| `docs/` | Documentation only | `docs/codebase-analysis-v2`, `docs/export-compliance-closed-source` |
| `refactor/` | Code restructuring | `refactor/remove-ios-raw-unit` |
| `chore/` | Tooling, CI, maintenance | `chore/gitignore-macos-framework-binary`, `chore/upgrade-android-toolchain` |
| `review-pr-<N>` | Review-specific branch | `review-pr-21`, `review-pr-22` |
| `pr-<N>` | PR checkout | `pr-34`, `pr-35` |
| `product/` | Long-lived product milestone | `product/scaffold-v0`, `product/desktop-ui-ux-redesign` |

Scopes in commit messages should match the branch type. Both follow the Conventional Commits convention defined in `docs/governance/git-commit-message-convention.md`.

## Merging Strategy

All PRs merge into the default branch (`main` via GitHub merge commits). Squash merges are not used — branch topology is preserved via `git log --graph`.

## Git Worktree for Parallel Development

This project already uses git worktrees for PR review. Three are currently active:

```
/chanora                              → docs/codebase-analysis-v2
/tmp/opencode/chanora-pr34-review     → simplify-project-review
/tmp/opencode/chanora-pr35-review     → (detached HEAD)
/tmp/opencode/chanora-pr36-review     → pr-36-review
```

### Why Worktrees

- Review PRs without stashing or losing your working tree state
- Run long CI builds in one tree while editing in another
- Keep multiple feature branches checked out simultaneously
- Avoid `git stash` / `git checkout` churn

### Common Workflows

**Feature branch:**
```bash
git worktree add ../chanora-feat-x feat/my-feature
cd ../chanora-feat-x
# work, commit, push, open PR
```

**Hotfix (from main):**
```bash
git worktree add ../chanora-hotfix -b fix/urgent-bug origin/main
cd ../chanora-hotfix
# fix, commit, push, open PR
# merge PR, then: git worktree remove ../chanora-hotfix
```

**Review branch (checkout a PR):**
```bash
gh pr checkout 36 --detach
# or via worktree:
git worktree add ../chanora-review-36 pr-36-review
```

### Cleanup

```bash
git worktree remove ../chanora-feat-x        # after merge
git worktree prune                            # clean stale entries
git branch -d feat/my-feature                 # delete merged branch
```

## PR Stacking Pattern

This project uses stacked PRs where features are built on top of each other:

```
main ← #39 (refactor/remove-ios-raw-unit)
         └─ #38 (fix/ios-audio-session)
              └─ #37 (feat/desktop-silero-vad)
```

To create a stacked PR:

1. Branch from the base PR's branch (not `main`)
2. Push and open PR targeting the base PR's branch
3. After base merges, rebase onto `main` and update the target

For managing stacks, `gh` CLI is sufficient:

```bash
# Create dependent branch
git checkout -b feat/next-thing origin/feat/base-thing
# After base merges:
git rebase origin/main && git push --force-with-lease
# Update PR target via GitHub UI or:
gh pr edit <number> --base main
```

## Local CI Mirroring

The project CI (defined in `.github/workflows/`) runs platform builds (Android, Windows, macOS, iOS), clippy, and tests. To mirror locally before pushing:

```bash
# Rust checks (fast, run always)
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

# Flutter checks
cd flutter && flutter analyze

# Platform builds (run before PR)
cargo build --target aarch64-linux-android
cargo build --target x86_64-pc-windows-msvc
cargo build --target aarch64-apple-darwin
```

Tip: Use `act` (https://github.com/nektos/act) to run GitHub Actions locally for full CI parity:

```bash
act pull_request  # runs the PR workflow locally via Docker
```

## Quick Reference

| Task | Command |
|------|---------|
| New feature | `git worktree add ../chanora-X -b feat/X origin/main` |
| Review PR | `gh pr checkout N` or `git worktree add ../review-N pr-N-review` |
| Cleanup after merge | `git worktree remove ../chanora-X && git branch -d feat/X` |
| Check worktrees | `git worktree list` |
| Local CI | `cargo clippy --workspace --all-targets -- -D warnings && cargo test --workspace` |