chanora/docs/references/branch-management-workflow.md

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:

git worktree add ../chanora-feat-x feat/my-feature
cd ../chanora-feat-x
# work, commit, push, open PR

Hotfix (from main):

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):

gh pr checkout 36 --detach
# or via worktree:
git worktree add ../chanora-review-36 pr-36-review

Cleanup

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:

# 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:

# 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:

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