브랜치 전략과 PR 워크플로우

왜 main에 직접 push하지 않을까

main 브랜치는 항상 동작하는 안정된 코드가 있어야 하는 곳입니다. main에 직접 push하면 다음 문제가 생깁니다:

• 코드 리뷰 없이 합쳐짐 - 버그가 있는 코드가 그대로 main에 들어갈 수 있습니다.
• 충돌 위험 증가 - 여러 명이 동시에 main에 push하면 충돌이 빈번해집니다.
• 되돌리기 어려움 - 문제가 생겼을 때 어떤 커밋이 원인인지 파악하기 어렵습니다.
• 작업 기록이 불명확 - "누가, 왜, 무엇을" 변경했는지 추적이 어렵습니다.

간단한 브랜치 전략

소규모 팀에 적합한 간단한 브랜치 전략입니다:

  
    
  
  
    
  

main (항상 안정된 상태)
  │
  ├── feature/login ──── PR ──── merge → main
  │
  ├── feature/signup ─── PR ──── merge → main
  │
  └── fix/typo ────────── PR ──── merge → main

워크플로우

1. main에서 새 브랜치 생성 - 작업 단위마다 브랜치를 만듭니다.
2. 브랜치에서 작업 - 코드 작성, 커밋, push
3. PR(Pull Request) 생성 - GitHub에서 main으로 merge 요청
4. 코드 리뷰 - 팀원이 코드를 확인하고 피드백
5. merge - 리뷰 완료 후 main에 합치기
6. 브랜치 삭제 - merge된 브랜치는 삭제

브랜치 네이밍 규칙

  
    
  
  
    
  

feature/기능명    → 새 기능 개발
fix/버그명        → 버그 수정
refactor/대상    → 리팩토링
docs/문서명      → 문서 작업

예시:
feature/login-page
fix/header-overflow
docs/readme-update

스타일 관련 작업은 어떤 prefix를 쓰나요?

브랜치 prefix는 작업의 의도를 기준으로 나누는 것을 추천합니다. 스타일 작업도 같은 원칙을 적용하면 됩니다.

• 새 UI 추가 → feature/ (예: feature/login-page)
• UI 버그 수정 → fix/ (예: fix/header-overflow)
• 스타일 구조 개선 → refactor/ (예: refactor/button-styles)

별도로 ui/ 같은 prefix를 만들기보다, 위 규칙으로 충분히 구분됩니다. 팀에서 정말 필요하다고 느낄 때만 추가하세요.

PR 작성법 기본

Pull Request(PR)는 "내 브랜치의 변경사항을 main 브랜치로 가져가(pull) 주세요"라는 요청입니다. 내가 main에 직접 넣는(push) 것이 아니라, main 쪽에서 내 코드를 가져가도록 요청하는 관점입니다.

PR을 만드는 흐름

  
    
  
  
    
  

# 1. main에서 새 브랜치 생성
git switch main              # main 브랜치로 이동
git pull origin main         # 원격 저장소의 최신 코드를 로컬에 가져옴
git switch -c feature/login-page  # 새 브랜치를 만들면서 이동

# 2. 작업 후 커밋
git add .
git commit -m "로그인 페이지 UI 구현"

# 3. 원격에 push
git push origin feature/login-page  # 원격 저장소에 내 브랜치를 push

push 후 GitHub 저장소 페이지에 가면 "Compare & pull request" 버튼이 표시됩니다. 클릭하여 PR을 생성합니다.

PR에 포함할 내용

PR 리뷰와 merge 과정

PR이 생성되면 팀원이 코드를 리뷰합니다.

코드 리뷰 방법

1. PR 페이지에서 "Files changed" 탭을 클릭하면 변경된 코드의 diff를 확인할 수 있습니다.
2. 코드의 특정 줄을 클릭하면 코멘트 입력란이 나타납니다. 의견을 작성한 뒤 "Start a review"를 클릭하면 리뷰에 코멘트가 추가됩니다. (바로 보내지 않고 모아뒀다가 한꺼번에 제출할 수 있습니다.)
3. 리뷰를 마치면 우측 상단의 "Submit review" 버튼을 클릭합니다.
4. 세 가지 옵션 중 하나를 선택합니다:
   • Approve - 코드에 문제가 없어 merge해도 좋다는 승인
   • Request changes - 수정이 필요한 부분이 있다는 요청
   • Comment - 승인/반려 없이 의견만 남기기

merge 방법

저장소에 설정된 조건(리뷰 Approve, 코멘트 resolve 등)이 모두 충족되면 PR 하단에 녹색 "Squash and merge" 버튼이 활성화됩니다. 이 버튼을 클릭하면 해당 브랜치의 변경사항이 main 브랜치에 합쳐집니다.

충돌(conflict) 발생 시 기본 대응

두 명이 같은 파일의 같은 부분을 수정하면 충돌이 발생합니다. 흔한 상황이니 걱정하지 않아도 됩니다.

충돌 해결 순서

  
    
  
  
    
  

# 1. main의 최신 변경사항을 가져온다
git switch main
git pull origin main

# 2. 내 브랜치로 돌아가서 main을 merge한다
git switch feature/login-page
# main의 변경사항을 내 브랜치에 합침 (merge)
# merge는 다른 브랜치의 변경사항을 현재 브랜치에 합치는 것입니다.
git merge main

충돌이 발생하면 Git이 해당 파일에 아래와 같은 표시를 추가합니다.

  
    
  
  
    
  

<<<<<<< HEAD
내 브랜치의 코드
=======
main 브랜치의 코드
>>>>>>> main

• <<<<<<< HEAD ~ ======= - 내 브랜치에서 수정한 코드
• ======= ~ >>>>>>> main - main 브랜치에서 수정된 코드

  
    
  
  
    
  

# 3. 충돌 파일을 열어 수동으로 해결
# <<<<<<< HEAD
# 내 코드
# =======
# main의 코드
# >>>>>>> main

# 4. 충돌 해결 후 커밋
git add .
git commit -m "main 브랜치 merge 충돌 해결"

# 5. push
git push origin feature/login-page

---

정리 - 브랜치를 나눠 작업하고, PR로 코드 리뷰를 거쳐 merge하는 것이 팀 협업의 기본 워크플로우입니다. 충돌은 흔한 상황이며, 충돌 마커를 이해하면 쉽게 해결할 수 있습니다.

다음 세션에서는 지금까지 배운 내용을 종합한 팀 프로젝트 시작 체크리스트를 제공합니다.