tomevault-io Git Workflow Guide
Branch Strategy (Git Flow)
┌─────────────────────────────────────────────────────────────────┐
│ Branch Flow │
├─────────────────────────────────────────────────────────────────┤
│ │
│ main ──────────────────────────────────────────────────────── │
│ ↑ │
│ │ (release merge) │
│ │ │
│ develop ───────────────────────────────────────────────────── │
│ ↑ ↑ ↑ │
│ │ │ │ (PR merge) │
│ │ │ │ │
│ feature/ refactor/ fix/ │
│ xxx xxx xxx │
│ │
└─────────────────────────────────────────────────────────────────┘
Branch Naming Convention
| Type | Pattern | Example |
|---|---|---|
| Feature | feature/{scope}-{description} |
feature/chat-crud-api |
| Refactor | refactor/{scope}-{description} |
refactor/reward-fanout-exchange |
| Fix | fix/{scope}-{description} |
fix/auth-token-refresh |
| Hotfix | hotfix/{description} |
hotfix/critical-security-patch |
| Release | release/v{version} |
release/v1.2.0 |
Branch Rules
- Base Branch:
develop(NOTmain) - Feature/Refactor/Fix: Branch from
develop, merge back todevelop - Hotfix: Branch from
main, merge to bothmainanddevelop - Release: Branch from
develop, merge tomainafter QA
⚠️ CRITICAL: PR은 반드시
develop브랜치를 base로 생성해야 합니다.
gh pr create --base develop(NOT--base main)- main으로 잘못 머지하면 main → develop PR을 추가로 생성해야 합니다.
Commit Convention (Conventional Commits)
<type>(<scope>): <description>
[optional body]
[optional footer]
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Types
| Type | Description | Example |
|---|---|---|
feat |
New feature | feat(chat): add message persistence |
fix |
Bug fix | fix(auth): resolve token refresh race condition |
refactor |
Code refactoring | refactor(chat_worker): apply Clean Architecture |
docs |
Documentation | docs: add API specification |
test |
Tests | test(chat_worker): add unit tests for intent classifier |
chore |
Maintenance | chore: update dependencies |
style |
Formatting | style: fix linting errors |
perf |
Performance | perf(rag): optimize vector search |
Scope Examples
auth,users,chat,chat_worker,location,characterinfra,k8s,terraform,helmci,cd,pipeline
PR Procedure
1. Create Branch
# From develop branch
git checkout develop
git pull origin develop
git checkout -b feature/chat-crud-api
2. Work & Commit
# Make changes
git add .
git commit -m "feat(chat): add message persistence"
3. Push & Create PR
# Push to remote
git push -u origin feature/chat-crud-api
# Create PR via gh CLI
gh pr create --base develop --title "feat(chat): add CRUD API for messages" --body "$(cat <<'EOF'
## Summary
- Add message persistence endpoints
- Implement ChatRepository with PostgreSQL
## Test plan
- [ ] Unit tests pass
- [ ] Integration tests with DB
- [ ] Manual API testing
🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"
4. PR Review & Merge
- Wait for CI checks (GitHub Actions)
- Request review from team members
- Address review comments
- Squash and merge to
develop
PR Template
## Summary
<1-3 bullet points describing changes>
## Related Issue
Closes #123
## Test plan
- [ ] Unit tests pass (`pytest apps/{service}/tests/unit -v`)
- [ ] Integration tests pass
- [ ] Manual testing completed
## Checklist
- [ ] Code follows project conventions
- [ ] Tests added/updated
- [ ] Documentation updated (if needed)
- [ ] No breaking changes (or documented)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
CI/CD Integration
GitOps 플로우
ArgoCD가
develop브랜치를 바라봄 (Staging 아님, Dev 환경 직접 배포)
PR → develop 머지 → ArgoCD auto-sync → Dev 클러스터 반영
Branches Triggering CI
| Branch | CI Trigger | Deploy Target |
|---|---|---|
main |
Push | (예비, 현재 미사용) |
develop |
Push, PR | Dev (ArgoCD sync) |
feature/* |
PR only | - |
refactor/* |
PR only | - |
fix/* |
PR only | - |
Quality Gates
- Linting (ruff, black)
- Type checking (mypy)
- Unit tests (pytest)
- Security scan (SonarCloud)
Quick Reference
Common Commands
# Start new feature
git checkout develop && git pull && git checkout -b feature/new-feature
# Sync with develop
git fetch origin develop && git rebase origin/develop
# Create PR
gh pr create --base develop
# Check PR status
gh pr status
# View PR in browser
gh pr view --web
Useful gh CLI Commands
# List open PRs
gh pr list
# Check out PR locally
gh pr checkout 123
# Approve PR
gh pr review --approve
# Merge PR
gh pr merge --squash --delete-branch
Reference Files
- Branch naming: See branch-naming.md
- Commit examples: See commit-examples.md
- Token streaming fix: See token-streaming-fix.md - Worktree + 트러블슈팅 사례
- PR templates: See
.github/PULL_REQUESTS/ - Issue templates: See
.github/ISSUE_TEMPLATE/
Converted and distributed by TomeVault — claim your Tome and manage your conversions.