Git Guide

가이드 개요

이 가이드는 GitHub Flow와 Squash and Merge 전략을 기반으로 합니다. 핵심 목표는 깨끗한 메인 브랜치 히스토리 관리와 Jira 티켓 추적성 확보입니다.

📌 팀 브랜치 네이밍 컨벤션

브랜치 네이밍은 Jira 이슈 화면에서 브랜치, 커밋, PR이 모두 자동 연결되도록 작성하는 것이 원칙입니다.

1️⃣ 기본 원칙 (필수)

Jira 이슈 키는 반드시 포함합니다.
전부 **소문자 + 하이픈(-)**을 사용합니다.
공백, 한글, 특수문자는 사용하지 않습니다. ❌
형식: <type>/<JIRA-KEY>-<short-description>

2️⃣ 브랜치 타입 정의

타입	용도	예시
`feature`	신규 기능 개발	`feature/MR-101-user-signup`
`bugfix`	버그 수정	`bugfix/MR-102-login-timeout`
`hotfix`	운영 긴급 수정	`hotfix/MR-103-prod-db-error`
`refactor`	코드 리팩토링	`refactor/MR-104-auth-service`
`chore`	설정/빌드/단순 작업	`chore/MR-105-ci-config`
`test`	테스트 코드	`test/MR-106-unit-test`
`docs`	문서 수정	`docs/MR-107-api-spec`

3️⃣ 단기 설명 규칙 (short-description)

2~5 단어 정도를 권장합니다.
무엇을 하는지 명확하게 표현합니다.
동사 또는 명사로 시작합니다.
✅ 좋은 예: login-api, payment-timeout-fix, user-auth-refactor
❌ 나쁜 예: fix, test, temp, abc

4️⃣ 예외 규칙 (Jira 없는 작업)

Jira 이슈가 반드시 필요한 팀이므로 기본적으로는 사용하지 않기를 권장하나, 꼭 필요한 경우 다음과 같이 작성합니다.

chore/no-jira-update-readme
experiment/spike-oauth

🚀 머지 및 배포 워크플로우

1️⃣ 브랜치 운영 시스템

develop: 개발 (통합 개발 브랜치)
stage: 스테이징 환경 (QA 및 검증)
production: 상용 배포 브랜치

2️⃣ PR & 커밋 규칙

PR 제목: [JIRA-KEY] 설명 (예: [MR-101] 로그인 API 구현)
커밋 메시지: JIRA-KEY 설명 (예: MR-101 로그인 API 구현)
머지 방식: Squash and Merge

[!NOTE] 브랜치, 커밋, PR 중 하나에만 Jira 키가 있어도 연결이 되지만, 세 군데 모두 포함하는 것이 가장 좋습니다.

3️⃣ 상세 워크플로우

워크플로우 시각화 (GitHub Flow)

gitGraph
    checkout develop
    commit id: "Initial Commit"
    branch feature/MR-101
    checkout feature/MR-101
    commit id: "feat: login ui"
    commit id: "feat: login logic"
    checkout develop
    merge feature/MR-101 tag: "Squash & Merge"
    commit id: "deploy to stage"
    branch stage
    checkout stage
    commit id: "QA Pass"
    checkout production
    merge stage tag: "Release"

PR 및 머지 과정

sequenceDiagram
    participant Dev as Developer (Local)
    participant GH as GitHub (Origin)
    participant Reviewer as Reviewers

    Dev->>Dev: 1. Feature Development
    Dev->>Dev: 2. git rebase origin/develop
    Dev->>GH: 3. git push origin feature/xxx
    Dev->>GH: 4. Create Pull Request
    Reviewer->>GH: 5. Code Review & Approval
    GH->>GH: 6. Squash and Merge to develop
    Note over GH: History is flattened to a single commit

Rebase: 기능 개발 완료 후 develop 브랜치를 기준으로 로컬 커밋을 정리합니다.
```
git fetch origin
git rebase origin/develop
```
Pull Request: GitHub에서 PR을 생성하고 리뷰를 요청합니다.
Squash and Merge: 리뷰 승인 후 머지하여 히스토리를 깔끔하게 유지합니다.

Git Guide

On this page