# 1. Branching Model (Git-Flow 방식)

- 각 브랜치는 사용하는 시점에서 생성을 하고 이슈가 해결(PR까지 완료) 된 경우 제거한다.
    - 단, main, develop 브랜치는 **절대 삭제하지 않는다**.

## 1.1. 브랜치 명명 규칙

- 형식 : 타입`/#이슈번호-작업요약`
- 규칙
    - `/` : 브랜치를 폴더 구조로 묶어준다.
    - `-` : 단어 사이를 연결하며, 띄어쓰기는 금지한다.
    - `#` : 이슈 추적을 위해 이슈 번호를 명시한다.
    - **영문 소문자**만 사용한다.(한글 금지)
- 예시
    - feature/#1-admin-login
    - fix/#20-jwt-error
- 예외
    - main, develop 브랜치의 명칭은 변하지 않는다.
    - release 브랜치는 `release/v버전` 의 형식으로 작성한다.

## 1.2. 브랜치 전략표

| 타입 | 의미 | 브랜치 명 예시 | 생성위치 |
| --- | --- | --- | --- |
| main | 배포 가능 최신 상용 상태 | main | - |
| develop | 다음 배포를 위한 통합 브랜치 | develop | - |
| feature | 새로운 기능 개발 | feature/#1-admin-login | develop |
| fix | 개발 중 버그 수정 | fix/#20-jwt-error | develop, release |
| refactor | 기능 변경 없는 코드 개선 | refactor/#13-folder-structure | develop |
| hotfix | [긴급] 운영 서버 버그 수정 | hotfix/#99-prd-db-error | main |
| release | 배포 버전 준비 | release/v1.0.0 | develop |

## 1.3. Branch Life Cycle

### 1.3.1. ***준비 과정***

- main / develop 브랜치 생성 및 초기화

### 1.3.2. ***개발 과정***

1. develop 에서 feature 브랜치 생성해 개발한다. (이슈 생성 필수)
2. 개발 완료 후 devlop으로 **커밋 > PR > 머지**를 수행한다.
3. 개발 중 발견된 버그는 develop에서 fix 브랜치를 생성하여 수정한다. (이슈 생성 필수)
4. 위 과정을 반복하다 배포 스펙이 완성되면 배포 준비 단계로 넘어간다.

### 1.3.3. ***배포 준비 과정***

1. develop 에서 `release/vX.X.X` 브랜치를 생성한다. (Code Freeze 상태)
    - 이후 develop 에서는 다음 버전을 위한 개발을 진행해도 된다.
2. QA 중 발견된 버그는 release 브랜치에서 fix 브랜치를 생성해 release에 직접 커밋한다. (이슈 생성 필수)
3. 최종 테스트가 완료되면 배포 단계로 넘어간다.

### 1.3.4. ***배포 과정***

1. 정기 배포:
    - release 브랜치를 main 에 머지하고 해당 버전에 대한 태그를 붙인다.
    - 배포가 완료되면 release 브랜치를 develop 에 백머지(back-merge)하여 변경 사항을 동기화한다.
    - 두 브랜치에 머지가 완료되면 release 브랜치는 **삭제**한다.
2. 긴급 배포
    - main 에서 hotfix 브랜치를 생성하여 버그를 수정한다. (이슈 생성 필수)
    - 검증 원칙
        - hotfix 브랜치는 main 에 머지하기 전에 반드시 **로컬 테스트**와 **스테이징 검증**을 통과해야 한다.
        - 검증과정에서 발생하는 수정 사항은 오직 hotfix 브랜치 내부에서만 커밋한다.
        - 검증이 완료되기 전까지는 절대 main 브랜치에 PR을 머지하지 않는다.
    - 배포 및 동기화
        - 검증이 완료되면 main 에 머지하고 해당 버전에 대한 태그를 붙인다. (버전 patch 상승)
        - 동시에 develop 에도 백머지(back-merge)를 수행하여 다음 버전 개발에 반영되게 변경 사항을 동기화한다.
    - 모든 작업이 완료되면 hotfix 브랜치는 **삭제**한다.

# 2. Commit Message

- 형식: `타입: 설명 (이슈번호)`
    - 타입: [2.1. Commit Type](https://www.notion.so/Git-Version-Control-2ed4d57b3bf0805cb29fff784579d427?pvs=21) 참고
    - 설명: 언어 상관없이 편하게 내용 작성
    - 이슈번호
        - 일반: 해당 커밋이 어떠한 이슈의 참조인지 알려준다. (예: feat: 로그인 구현(#1))
        - 동작: 해당 커밋이 연결된 이슈의 상황을 변경함 (PR 작성시 확인)
            1. Close, Closes, Closed : 해당 커밋을 끝으로 이슈 닫기 (예: feat: 로그인 구현(Closes #1))
            2. Fix, Fixes, Fixed : 해당 커밋을 끝으로 버그 수정되어 이슈 닫기 (예: fix: DB 예외 처리(Fixes #21))
            3. Resolve, Resolves, Resolved : 무언가 해결이 되어 이슈 닫기 (예: feat: 푸시 구현(Resolves #13))

## 2.1. Commit Type

- 커밋의 메시지는 [Conventional Commits](https://www.conventionalcommits.org/ko/v1.0.0/) 의 규칙을 따른다.

> 커밋 메시지만 보고 소프트웨어의 버전을 올릴 수 있게 하자.
>
- 소프트웨어 버전은 `Major.Minor.Patch` 로 보통 세자리로 구성이 되는데 커밋 메시지만 보고도 세 자리 중 어디를 올려야 하는지에 대한 가이드이다. (초기 배포 시점의 계산이 아니라 배포 후 부터 계산한다.)

### **2.1.1. fix**

- 상황: 로직상의 오류, 오타, 크래시 등을 수정했으나 기능 명세는 변하지 않았다.
- 커밋: `fix: 화면 오타 수정 (Fixes #23)`
- 브랜치
    - `hotfix` 브랜치: 이미 배포된 버전을 긴급 수정하는 것이므로 배포 시 `Patch 버전이 상승` 한다.
    - `fix` 브랜치: 다음 버전을 출시 하기 위한 안정화 과정이므로 버전 숫자는 변하지 않는다.
    - `feature` / `develop` 브랜치: 다음 버전을 출시 하기 위한 개발 과정이므로 버전 숫자는 변하지 않는다.

### **2.1.2. feat**

- 상황:  기획대로 새로운 기능이 코드에 추가되었다.
- 커밋: `feat: 외부 결제 추가 (Closes #34)`
- 브랜치
    - `feature` 브랜치: 오직 이 브랜치에서만 사용한다. 당장 버전이 변하지는 않지만 이후 배포가 되면 `Minor 버전 상승` 의 근거가 된다.

### **2.1.3. BREAKING CHANGE**

- 상황: 이전 버전과 완전 호환되지 않는 기술적인 변경이 발생한다.
- 커밋: `feat!: 유저 API 전체 변경` (해당 타입의 뒤에 `!`를 붙인다.)
- 브랜치
    - `feature` 브랜치: 다음 버전을 위한 대공사이므로 개발 단계에서 수행한다.
    - 다른 브랜치: 선언 불가
    - feature > develop > release > main 으로 머지 되면 `Major 버전이 상승` 한다.
- 해당 타입은 다른 타입에 붙어서 사용되므로 독자적으로 사용되지는 않는다.

---

### **2.1.4.**  test

- 상황
    1. 새로운 테스트 코드 작성할 때
    2. 기존 테스트 코드에 문제가 있어 테스트 코드만 수정할 때 (기능의 수정은 이루어지지 않는다.)
    3. 테스트 데이터를 수정하거나 리팩토링 할 때
- 커밋: `test: 로그인 API 테스트`
- 브랜치
    - 개발 수정 가능한 모든 브랜치 어디서든 사용 가능하다.

### **2.1.5.** chore

- 상황: 소스 코드는 건드리지 않고 빌드 설정, 패키지 업데이트, 라이브러리 설치 등을 수정했다.
- 커밋: `chore: JSON 패키지 업데이트`
- 브랜치
    - 개발 수정 가능한 모든 브랜치 어디서든 사용 가능하다.

### **2.1.6.** refactor

- 상황: 기능과 결과는 100% 동일하지만 내부 코드 구조를 개선하거나 성능을 최적화했다.
- 커밋: `refactor: 로그인 화면 개편`
- 브랜치
    - `feature` / `refactor` 브랜치: 주로 개발 단계에서 사용한다.
    - `fix` 브랜치: 사용은 가능하나 브랜치의 역할이 다르니 최소한으로 사용한다.
    - 다른 브랜치: 선언 불가

### **2.1.7.** style

- 상황: 코드의 동작과 전혀 상관없는 띄어쓰기, 줄 바꿈, 들여쓰기 등을 수정했다.
- 커밋: `style: 불필요한 공백 제거`
- 브랜치
    - 개발 수정 가능한 모든 브랜치 어디서든 사용 가능하다.
- 표

    | **브랜치 (Branch)**  |     **feat**      |      **fix**      | **BREAKINGCHANGE** | **test / chore / style** |   **refactor**    | **비고 (Note)**                           |
    |:-----------------:|:-----------------:|:-----------------:|:------------------:|:------------------------:|:-----------------:|:----------------------------------------|
    |     **main**      |         ❌         |         ❌         |         ❌          |            ❌             |         ❌         | **Merge Only**<br>(직접 커밋 금지)            |
    |    **develop**    |         ❌         |         ❌         |         ❌          |            ❌             |         ❌         | **Merge Only**<br>(직접 커밋 금지)            |
    |  **feature/...**  | **⭕**<br>**(주력)** |    ⭕<br>(자체수정)    | **⭕**<br>**(가능)**  |            ⭕             |         ⭕         | 모든 작업이 가능한 **자유 구역**                    |
    |    **fix/...**    |         ❌         | **⭕**<br>**(주력)** |         ❌          |            ⭕             |    🔺<br>(최소한)    | 기능 추가 절대 금지<br>테스트 보강 가능                |
    |  **hotfix/...**   |         ❌         | **⭕**<br>**(주력)** |         ❌          |            ⭕             |         ❌         | **[긴급]** 긴급 수정 및<br>검증용 테스트만 허용         |
    |  **release/...**  |         ❌         | **⭕**<br>**(주력)** |         ❌          |            ⭕             |         ❌         | **[배포전]** 안정화 및<br>검증용 테스트만 허용          |
    | **refactor/...**  |         ❌         |         ❌         |         ❌          |            ⭕             | **⭕**<br>**(주력)** | 동작 변경 금지 (fix 불가)<br>기능 추가 금지 (feat 불가) |

---

# 3. Pull Request(PR) Message

- 프로젝트 최상단 폴더에 `.gitea/pull_request_template.md`  혹은 `.github/` 폴더에 저장하면 PR 생성시 자동으로 내용이 채워진다.
- 타이틀
    - PR 은 결국 main 이나 develop 브랜치의 커밋이 되기에 타이틀은 [2. Commit Message](https://www.notion.so/Git-Version-Control-2ed4d57b3bf0805cb29fff784579d427?pvs=21)를 따라서 작성한다.
    - 형식: `타입: 작업한 커밋들 요약 설명 (이슈번호)`
- 본문

    ```markdown
    ## 📋 작업 요약
    - {작업 3줄 요약}
    
    ## 🔗 관련 이슈 (Related Issues)
    Closes #
    
    ## 🛠️ 작업 내용 (Changes)
    - [ ] {작업 내용 1}
    - [ ] {작업 내용 2}
    
    ## 📢 리뷰어 참고 사항 (To Reviewers)
    - 없을시 비워둠
    - {리뷰어 참고 사항}
    
    ## ✅ 체크리스트 (Self Checklist)
    - [ ] 빌드(Build)가 성공적으로 수행되었는가?
    - [ ] 모든 단위 테스트(Unit Test)를 통과하였는가?
    - [ ] 불필요한 로그나 주석을 제거하였는가?
    - [ ] 컨벤션(Clean Architecture, Naming)을 준수하였는가?
    - [ ] 기밀 정보(비밀번호, 키 등)가 하드코딩 되어있지 않은가?
    
    ## 📸 스크린샷 / 테스트 로그 (Screenshots/Logs)
    - 없을시 비워둠
    ```
  // 테스트 로그 작성
    ```
    ```


---

# 4. 태그(Tag)를 붙이는 2가지 타이밍

- 태그(Tag)는 개발자가 코드에 찍는 **최종 승인 도장**으로, 아무때나 찍는 게 아니라 사용자에게 배포되는 버전 번호가 확정되는 순간에만 작성한다.
- 태그는 오직 main 브랜치에 코드가 머지된 직후에만 붙이는 것을 원칙으로 한다.

## 4.1. 정기 배포

- 상황: release/v1.0.0 브랜치에서 모든 QA를 끝내고 main 브랜치에 PR 후 merge 진행
- 버전: v1.0.0 → v1.1.0
- 태그: v1.1.0

## 4.2. 긴급 배포

- 상황: hotfix/… 브랜치에서 main에서 발생한 급한 오류를 해결하고 main 브랜치에 PR 후 merge 진행
- 버전: v1.1.0 → v1.1.1
- 태그: v1.1.1