Convention
Git Flow 컨벤션
Allra 프로젝트의 Git 브랜치 전략 및 워크플로우
Git Flow 컨벤션
Allra 프로젝트에서 사용하는 Git 브랜치 전략과 워크플로우에 대한 가이드입니다.
📋 목차
브랜치 구조
브랜치 타입
1. Main Branches
main (운영 브랜치)
- 목적: 프로덕션 배포용 브랜치 ( 운영계와 연결, 수동 배포 필요 )
- 특징:
- 모든 기능이 최종적으로 병합되는 브랜치
- 병합 즉시 프로덕션 환경에 배포
- 항상 안정적인 상태 유지
- 병합 소스:
develop
develop (기본 브랜치)
- 목적: 개발 통합 브랜치
- 특징:
- 개발 중인 코드가 모이는 브랜치
- 기능이 안정화되면
main브랜치로 병합 ( rebase 방식 ) - 일일 개발 작업의 기준점
- 병합 소스:
feature/*,fix/*,refactor/*,hotfix/*,e2e/*,qa/*
2. Supporting Branches (보조 브랜치)
feat/* - 기능 개발
- 분기:
develop - 병합:
develop - 명명 규칙:
feat/[기능명]또는feat/[이슈번호] - 예시:
feat/login-pagefeat/646(이슈 번호)feat/impersonation
fix/* - 버그 수정
- 분기:
develop - 병합:
develop - 명명 규칙:
fix/[버그명]또는fix/[이슈번호] - 예시:
fix/2(이슈 번호)fix/pdf-viewer-error(버그명)
refactor/* - 코드 리팩토링
- 분기:
develop - 병합:
develop - 명명 규칙:
refactor/[목적]또는refactor/[이슈번호] - 특징:
- 기존 기능에 영향을 주지 않는 코드 개선
- 코드 구조 정리 및 최적화
- 작은 단위로 나누어 작업 (충돌 방지)
- 예시:
refactor/cleanup-auth-modulerefactor/optimize-performancerefactor/644
e2e/* - E2E 테스트
- 분기:
develop - 병합:
develop - 명명 규칙:
e2e/[이슈번호]또는e2e/[테스트명] - 특징: End-to-End 테스트 작성 및 개선 ( 테스트 케이스 추가 )
- 예시:
e2e/663e2e/contract-flow
qa/* - QA 테스트
- 분기:
develop - 병합:
develop - 특징: QA 환경 테스트용 브랜치 ( 개발계와 연결, 자동 배포 )
- 예시:
qa/1(이슈 번호)qa/login-page(테스트명)
hotfix/* - 긴급 수정
- 분기:
develop,main - 병합:
develop,main( 이후 즉시 main 브랜치 혹은 develop 브랜치와 동기화 필요 ) - 명명 규칙:
hotfix/[이슈명]또는hotfix/[이슈번호] - 특징: 프로덕션 긴급 버그 수정용
- 예시:
hotfix/security-patchhotfix/3(이슈 번호)
⚠️ Hotfix 주의사항:
- 보통
develop브랜치에서 분기하고 수정 완료 후develop에 먼저 병합 - 반드시
main에도 즉시 병합 (동기화, 수동 배포 필요) - 경우에 따라 cherry-pick 방식으로 main에는 hotfix 브랜치에서 커밋한 내용만 병합되도록 필요할 수 있음 ( develop 브랜치에서 아직 작업 중이지만 운영계에 넣으면 안되는 작업이 있는 경우 )
워크플로우
기본 개발 플로우
1. 기능 개발 시작
# develop 브랜치 최신화
git checkout develop
git pull origin develop
# 새 기능 브랜치 생성
git checkout -b feat/646
# 개발 진행...
git add .
git commit -m "✨ 사업자번호 검증 후 상호명 입력 처리 로직 구현"
# 원격 저장소에 Push
git push origin feat/646추가로, cursor의 commands기능을 사용하여 자동으로 commit 메시지를 생성하고 있습니다. 그래서 좀 더 실무적인 과정은 다음과 같아요.
# develop 브랜치 최신화
git checkout develop
git pull origin develop
# 새 기능 브랜치 생성
git checkout -b feat/646
# cursor tab에서 /commit 명령어 입력하여 자동으로 커밋 메시지를 생성하고 커밋
# 만약 올바르지 않은 커밋이 들어갔다면 직접 입력
git reset --mixed HEAD~1
git commit -m "✨ 사업자번호 검증 후 상호명 입력 처리 로직 구현"
# 원격 저장소에 Push
git push origin feat/6462. Pull Request 생성 및 병합
- GitHub에서 Pull Request 생성
- 코드 리뷰 진행 ( coderabbitai의 자동 코드 리뷰 혹은 직접 리뷰 )
- 리뷰 승인 후
develop브랜치에 병합 - 로컬 브랜치 삭제
# 원격 저장소에서 PR 생성
# 로컬 브랜치 삭제
git branch -d feat/646commit과 마찬가지로 cursor의 commands기능을 사용하여 자동으로 PR 생성을 진행하고 있습니다.
# cursor tab에서 /pr 명령어 입력하여 자동으로 PR 생성
# 원격 저장소에서 PR 검증 후 수정
# 로컬 브랜치 삭제
git branch -d feature/login-page3. 긴급 수정 플로우 (Hotfix)
프로세스 상으로는 위 사진이고 실제 코드로 치면 다음과 같아요.
# develop에서 hotfix 브랜치 생성
git checkout develop
git pull origin develop
git checkout -b hotfix/3
# 긴급 수정 및 커밋
git add .
git commit -m "🔒 보안 취약점 패치"
# 원격 저장소에 Push
git push origin hotfix/3
# cursor tab에서 /pr 명령어 입력하여 자동으로 PR 생성
# 원격 저장소에서 PR 검증 후 수정
# Squash & Merge 방식으로 병합
# develop에 병합
git checkout develop
git pull origin develop
# main에 병합
git checkout main
git rebase develop
git push origin mainhotfix 이전
hotfix 이후
만약 develop 브랜치에서 아직 main 브랜치로 들어가면 안되는 작업이 있다면 다음과 같이 작업할 수 있어요. ( 노션 기준, 메인 브랜치에 먼저 병합되고 나서 develop 브랜치에 병합하는 경우 )
4. 릴리즈 플로우
# develop이 안정화되면 main으로 병합
git checkout main
git pull origin main
git rebase develop
git push origin main커밋 메시지 컨벤션
기본 형식
[이모지 타입] 커밋 메시지 (#PR번호)커밋 타입
| 이모지 | 타입 | 설명 | 예시 |
|---|---|---|---|
| ✨ | Feature | 새로운 기능 추가 | [✨ Feature] 진행중인 계약 중복 체크 기능 추가 (#651) |
| 🐛 | Fix | 버그 수정 | [🐛 Fix] PDF 뷰어 에러 바운더리 추가 (#656) |
| ♻️ | Refactor | 코드 리팩토링 | [♻️ Refactor] DateRangePicker 공통 컴포넌트화 (#662) |
| 💄 | Design | UI/UX 개선 | [💄 DESIGN Q/A] 자동선정산 신청 모달 UI/UX 개선 (#654) |
| 🔧 | Config | 설정 변경 | [🔧 Config] 스토리북 mock 설정 개선 (#661) |
| 📝 | Docs | 문서 작업 | [📝 Docs] README 문서 개선 및 프로젝트 정보 추가 (#643) |
| 🚀 | Release | 릴리즈 | [🚀 Release] 상품마진 고도화 2차 배포 (#638) |
| ✅ | Test | 테스트 추가/수정 | [✅ Test] E2E 테스트 케이스 추가 |
| ⚡️ | Perf | 성능 개선 | [⚡️ Perf] 이미지 로딩 최적화 |
| 🔒 | Security | 보안 이슈 수정 | [🔒 Security] XSS 취약점 패치 |
개별 커밋 메시지 (PR 전)
PR로 병합되기 전 개별 커밋은 간결한 형식을 사용합니다:
이모지 커밋 메시지예시:
✨ 로그인 페이지 UI 구현🐛 버튼 클릭 이벤트 버그 수정♻️ 계약 유형 관리 로직 리팩토링 및 에러 처리 개선✨ 계약 플로우 네비게이션 차단 기능 완성
팁: GitHub 이모지 코드(✨, 🐛 등)를 사용해도 됩니다.
실제 프로젝트 커밋 예시
# PR 병합 커밋 (Squash & Merge)
[♻️ Refactor] DateRangePicker 공통 컴포넌트화 및 중복 코드 대폭 제거 (#662)
[🐛 Fix] 남은 한도 음수 처리 방어 로직 추가 (#665)
[✨ Feature] 진행중인 계약 중복 체크 기능 추가 (#651)
# 개별 커밋
♻️ 계약 유형 관리 로직 리팩토링 및 에러 처리 개선
✨ 계약 플로우 네비게이션 차단 기능 완성 및 E2E 테스트 추가
🐛 계약 완료 시 네비게이션 차단 해제 타이밍 이슈 수정로컬 브랜치 관리
브랜치 최신화
# 정기적으로 develop 브랜치 최신화
git checkout develop
git pull origin develop
# 작업 중인 브랜치에 최신 변경사항 반영
git checkout feat/my-feature
git rebase develop충돌 최소화 팁
- 작은 단위로 자주 커밋: 큰 변경사항을 한 번에 커밋하지 않기
- 정기적으로 최신화: 하루에 한 번 이상
develop브랜치와 동기화 - 빠른 병합: PR을 오래 열어두지 않고 빠르게 병합
- 작은 PR: 한 번에 너무 많은 변경사항을 포함하지 않기
불필요한 브랜치 정리
# 로컬 브랜치 목록 확인
git branch
# 병합된 브랜치 삭제
git branch -d feature/old-feature
# 강제 삭제 (병합되지 않은 브랜치)
git branch -D feature/abandoned-feature
# 원격에서 삭제된 브랜치 로컬에서 제거
git fetch --prune실전 예시
Case 1: 새로운 기능 개발
# 1. 이슈 확인: #646 - 사업자번호 검증 기능 추가
# 2. 브랜치 생성
git checkout develop
git pull origin develop
git checkout -b feat/646
# 3. 개발 및 커밋
git add .
git commit -m "✨ 사업자번호 검증 후 상호명 입력 처리 로직 구현" # /commit 명령어 입력하여 자동으로 커밋 메시지를 생성하고 커밋
# 4. Push 및 PR
git push origin feat/646
# cursor tab에서 /pr 명령어 입력하여 자동으로 PR 생성
# 원격 저장소에서 PR 검증 후 수정
# 5. 코드 리뷰 후 병합
# Squash & Merge 방식으로 병합
# 6. 로컬 정리
git checkout develop
git pull origin develop
git branch -d feature/646
# 운영계 반영
git checkout main
git rebase develop
git push origin main
# argoCD 수동 배포 후 확인Case 2: 리팩토링 작업
# 1. 이슈 확인: #662 - DateRangePicker 공통 컴포넌트화
# 2. 브랜치 생성
git checkout develop
git pull origin develop
git checkout -b refactor/662
# 3. 리팩토링 작업 (작은 단위로 커밋)
git add src/components/DateRangePicker
git commit -m "♻️ DateRangePicker 공통 컴포넌트 추출" # /commit 명령어 입력하여 자동으로 커밋 메시지를 생성하고 커밋
git add src/pages
git commit -m "♻️ 중복 코드 제거 및 공통 컴포넌트 적용" # /commit 명령어 입력하여 자동으로 커밋 메시지를 생성하고 커밋
# 4. Push 및 PR
git push origin refactor/662
# cursor tab에서 /pr 명령어 입력하여 자동으로 PR 생성
# 원격 저장소에서 PR 검증 후 수정
# 5. 코드 리뷰 후 병합
# Squash & Merge 방식으로 병합
# 6. 로컬 정리
git checkout develop
git pull origin develop
git branch -d refactor/662
# 운영계 반영
git checkout main
git rebase develop
git push origin main
# argoCD 수동 배포 후 확인Case 3: 긴급 수정
# 1. 프로덕션 버그 발견: PDF 뷰어 에러
# 2. develop에서 hotfix 브랜치 생성
git checkout develop
git pull origin develop
git checkout -b hotfix/3
# 3. 긴급 수정
git add .
git commit -m "🐛 PDF 뷰어 Promise.withResolvers 폴리필 추가" # /commit 명령어 입령하여 자동으로 커밋 메시지를 생성하고 커밋
# 4. Push 및 PR
git push origin hotfix/3
# cursor tab에서 /pr 명령어 입력하여 자동으로 PR 생성
# 원격 저장소에서 PR 검증 후 수정
# 5. 코드 리뷰 후 병합
# Squash & Merge 방식으로 병합
# 6. 로컬 정리
git checkout develop
git pull origin develop
git branch -d hotfix/3
# 운영계 반영
git checkout main
git rebase develop
git push origin main
# argoCD 수동 배포 후 확인베스트 프랙티스
✅ DO
- PR 병합 시 Squash & Merge 사용
- 커밋 메시지에 이모지와 타입 명시
- PR 제목에 이슈 번호 포함
- 작은 단위로 자주 커밋하고 병합
- 코드 리뷰는 신속하게 진행
hotfix병합 후 반드시develop에도 rebase 필요- 브랜치 이름은 명확하고 간결하게
❌ DON'T
main브랜치에 직접 Push 금지, 대신develop브랜치에서 rebase 후 Push 필요- 리뷰 없이 병합 금지
- 오래된 브랜치 방치 금지
- 너무 큰 PR 생성 금지 (500줄 이상)
- 커밋 메시지 대충 작성 금지
hotfix후develop동기화 누락 금지, rebase 필요