🔃 Turtle Run Project Github Flow Guide

GitHub Flow 및 Branch 관리 가이드

TurtleRun 프로젝트는 기본적으로 GitHub Flow를 따르며, 아래와 같은 추가 규칙을 적용합니다.

1. GitHub Flow란?

GitHub Flow는 다음과 같은 간단한 원칙을 따르는 브랜치 기반 개발 전략입니다.

1. main 브랜치는 항상 배포 가능한 상태로 유지합니다.
2. 새로운 작업은 항상 별도의 브랜치(feature branch)에서 시작합니다.
3. 작업이 완료되면 Pull Request(PR)를 생성하여 코드 리뷰를 진행합니다.
4. 리뷰 및 테스트가 끝나면 main 브랜치에 merge합니다.
5. 배포가 필요하면 main 브랜치에서 배포합니다.

2. TurtleRun 프로젝트의 브랜치 관리 규칙

2-1. 브랜치 전략

• 브랜치는 main과 feature branch로 관리합니다.
• 각 작업은 GitHub Project에서 생성된 issue(티켓) 단위로 진행합니다.
• 티켓(issue) 하나당 일반적으로 하나의 브랜치/PR로 작업합니다.
• 브랜치 이름은 GitHub issue에서 Create branch로 생성했을 때의 이름(예: 123-fix-login-bug)을 사용합니다.

2-2. PR 및 Merge 규칙

• PR 제목은 작업 내용을 가장 잘 나타내는 commit convention에 맞는 메시지로 작성합니다.
• PR은 squash merge로 관리하여, main에는 하나의 커밋만 남도록 합니다.

3. 브랜치 의존성 관리 (Linear Workflow) ⭐️

여러 작업이 순차적으로 의존하는 경우, main 브랜치의 커밋 히스토리를 최대한 linear하게 유지하는 것을 원칙으로 합니다.

3-1. 브랜치 의존성 관리 방법

• 다른 작업에 의존성이 생기면, 해당 브랜치를 base로 새로운 브랜치를 생성합니다.
• base branch가 main에 merge되면, 의존 브랜치는 rebase pull을 받아 main을 linear하게 유지합니다.

예시 다이어그램 (gitGraph)

gitGraph
   commit id: "main"
   branch feat/some-screen
   checkout feat/some-screen
   commit id: "screen 작업 1"
   commit id: "screen 작업 2"
   commit id: "screen 작업 3"
   branch feat/some-other-screen
   checkout feat/some-other-screen
   commit id: "다른 screen 작업 1"
   commit id: "다른 screen 작업 2"
   checkout feat/some-screen
   checkout main
   merge feat/some-screen
   checkout feat/some-other-screen
   commit id: "(feat/some-screen 브랜치가 merge되면 main으로 rebase)"

Loading

예시 2 (feat/some-screen이 merge되고 rebase한 직후)

gitGraph
   commit id: "main"
   commit id: "feat: add some screen"
   branch feat/some-other-screen
   checkout feat/some-other-screen
   commit id: "다른 screen 작업 1"
   commit id: "다른 screen 작업 2"

Loading

예시 3 (feat/some-other-screen까지 merge된 직후)

gitGraph
   commit id: "main"
   commit id: "feat: add some screen"
   commit id: "feat: add some other screen"

Loading

git 명령어 예시

# base 브랜치에서 작업
git checkout -b feat/some-screen
# ...작업 후 PR & merge...

# 의존 브랜치 생성 (feat/some-screen에서 새로운 브랜치 생성)
git checkout -b feat/some-other-screen
# ...작업...

# feat/some-screen 브랜치가 main에 Squash merge된 후
git checkout feat/some-other-screen
git fetch origin
git rebase origin/main

4. (선택) Sub branch 전략

개인의 편의에 따라 sub branch 전략을 사용할 수 있습니다.
단, 관리가 복잡하고 병목이 생길 수 있으므로, 가급적 main과 feature branch만 사용하는 것을 권장합니다.

4-1. Sub branch 관리 방식

• 큰 작업은 sub branch를 두고, 해당 sub branch에서 여러 PR을 squash merge로 각각 단일 커밋으로 합칩니다.
• sub branch에는 feature branch PR이 squash merge로 합쳐진 단일 커밋들만 존재해야 합니다.
• sub branch를 main에 merge할 때는 fast-forward merge를 사용하여, feature PR의 squash 커밋들이 main에 그대로 남도록 합니다.
• 만약 sub branch에 squash commit 이외의 커밋(즉, sub branch에만 존재하는 커밋)이 하나라도 있다면, sub branch 전체를 squash merge해서 main에 merge합니다. (이 경우, sub branch의 커밋 히스토리는 main에 남지 않습니다)

Sub branch 관리 예시

1단계: sub branch 생성 및 첫 번째 feature PR 작업

gitGraph
   commit id: "main"
   branch feature/big-module
   checkout feature/big-module
   branch feature/module-1
   checkout feature/module-1
   commit id: "feat: add module 1"
   commit id: "refactor: refactor something"

Loading

2단계: 첫 번째 feature PR을 sub branch에 squash merge

gitGraph
   commit id: "main"
   branch feature/big-module
   checkout feature/big-module
   commit id: "feat: add module 1"

Loading

3단계: 두 번째 feature PR 작업 및 sub branch에 squash merge

gitGraph
   commit id: "main"
   branch feature/big-module
   checkout feature/big-module
   commit id: "feat: add module 1"
   branch feature/module-2
   checkout feature/module-2
   commit id: "feat: add module 2"
   commit id: "fix: fix some bug"
   commit id: "chore: remove comments"
   checkout feature/big-module
   merge feature/module-2

Loading

4단계: sub branch를 main에 fast-forward merge (최종 결과)

gitGraph
   commit id: "main"
   commit id: "feat: add module 1"
   commit id: "feat: add module 2"

Loading

⚠️ sub branch에 squash commit 이외의 직접 커밋이 없는 경우에만 fast-forward merge를 허용합니다. 이때 main에는 feature PR의 squash 커밋들이 그대로 보존됩니다.

5. 요약

• main과 feature branch 중심의 단순한 브랜치 전략을 권장합니다.
• 여러 작업이 의존하는 경우, 브랜치 의존성 관리(Linear Workflow)를 적극적으로 활용합니다.
• 대규모 작업이 필요한 경우에만 sub branch 전략을 사용하며, 관리 규칙을 반드시 준수합니다.
• 모든 PR은 squash merge를 기본으로 하되, sub branch의 경우 상황에 따라 forward merge를 사용합니다.
• 브랜치 의존성은 rebase로 main을 linear하게 유지합니다.