Edison Jwa
f509c370b3
Document branch naming conventions, git worktree setup, PR stacking patterns, and local CI mirroring recommendations.
137 lines
4.4 KiB
Markdown
137 lines
4.4 KiB
Markdown
# 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` |
|