SPMS/SPMS_API
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
362b0b0c5c
SPMS_API/SPMS.API/Documents/GitFlow.md

12 KiB
Raw Blame History

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 참고
    • 설명: 언어 상관없이 편하게 내용 작성
    • 이슈번호
      • 일반: 해당 커밋이 어떠한 이슈의 참조인지 알려준다. (예: 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

커밋 메시지만 보고 소프트웨어의 버전을 올릴 수 있게 하자.

  • 소프트웨어 버전은 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
    (직접 커밋 금지)
    develop ❌ ❌ ❌ ❌ ❌ Merge Only
    (직접 커밋 금지)
    feature/... ⭕
    (주력)    		 ⭕
    (자체수정)    		 ⭕
    (가능)    		 ⭕ ⭕ 모든 작업이 가능한 자유 구역
    fix/... ❌ ⭕
    (주력)    		 ❌ ⭕ 🔺
    (최소한)    		 기능 추가 절대 금지
    테스트 보강 가능
    hotfix/... ❌ ⭕
    (주력)    		 ❌ ⭕ ❌ [긴급] 긴급 수정 및
    검증용 테스트만 허용
    release/... ❌ ⭕
    (주력)    		 ❌ ⭕ ❌ [배포전] 안정화 및
    검증용 테스트만 허용
    refactor/... ❌ ❌ ❌ ⭕ ⭕
    (주력)    		 동작 변경 금지 (fix 불가)
    기능 추가 금지 (feat 불가)

3. Pull Request(PR) Message

  • 프로젝트 최상단 폴더에 .gitea/pull_request_template.md 혹은 .github/ 폴더에 저장하면 PR 생성시 자동으로 내용이 채워진다.

  • 타이틀

    • PR 은 결국 main 이나 develop 브랜치의 커밋이 되기에 타이틀은 2. Commit Message를 따라서 작성한다.
    • 형식: 타입: 작업한 커밋들 요약 설명 (이슈번호)

  • 본문

    ## 📋 작업 요약
- {작업 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