✍️ 이 글을 작성한 이유

이전에는 했던 팀 프로젝트에서는 Git 컨벤션을 세세히 정하지 않았다. 그래서 그때는 브랜치명을 각자 마음대로 정했고, 여러 기능을 동시에 개발할 때는 어떤 브랜치가 어떤 이슈를 다루고 있는지 헷갈릴 때가 많았다.

이번에는 팀원들과 함께 Git 컨벤션을 처음부터 꼼꼼히 정해보았고, 잘 정리했기에 이렇게 글로 남긴다.

👍 컨벤션이 좋은 이유

컨벤션 덕분에 브랜치를 만들거나 커밋 메시지를 작성할 때마다 별다른 고민 없이 일관된 형식으로 작성할 수 있게 됐다. 또한, 이슈와 PR도 모두 같은 형식으로 관리되어 리뷰 시에는 형식보다 내용이라는 핵심에 집중할 수 있어 훨씬 효율적이다.

다만, 컨벤션이라고 해서 고정된 것은 아니다. 프로젝트가 진행되면서 팀 회의를 통해 꾸준히 업그레이드할 예정이다. 예를 들어, 원래는 main과 dev만 있어서 이슈 단위로 작업한 브랜치를 바로 dev로 보냈다. 하지만 지금은 이슈 단위로 작업한 브랜치를 기능별 브랜치에 모은 뒤, dev에 병합하는 방식을 제안하면서 기능 브렌치도 추가하게 되었다.

---

1️⃣ 커밋 컨벤션

커밋 타입(Type)

• feat: 새로운 기능 추가
• fix: 버그 수정
• docs: 문서 수정
• style: 코드 포맷/세미콜론 등 비기능적 변경
• refactor: 코드 리팩토링
• test: 테스트 코드 추가/수정
• chore: 빌드, 패키지 등 기타 변경

커밋 구조

Type: 버튼 컴포넌트 구현

Body: (커밋에 대한 상세 설명)

커밋 작성 규칙

• 타입(Type)은 영어 소문자로 작성한다.
• Type:과 Body: 뒤에 한 칸 공백을 둔다.
• 제목(Subject)은 최대 50자 이내로 간결하게 작성한다.
• 한글로 작성하며 -하기 / -삭제 / -구현 / -추가 형태로 끝낸다.
• 끝에 마침표 및 특수기호는 금지한다.
• Subject와 Body 사이에 한 줄 개행한다.

커밋 예시

feat: 회원 가입 기능 구현

- SMS, 이메일 중복확인 API 개발
- 웹 클라이언트 사용 방식에서 서버 통신 방식으로 변경

2️⃣ 브렌치 전략

브렌치 종류

브랜치	역할 및 용도	유지 기간
main	실제 서비스용 브랜치(항상 안정적인 코드 유지)	항상 존재
dev	여러 기능을 통합·테스트하는 공용 개발 브랜치	항상 존재
feat	개별 기능 개발용 임시 브랜치	기능 개발 시 생성, 완료 후 삭제

---

브랜치 네이밍 규칙

• 공통 기능 개발

파트명/feat-기능명

ex) fe/feat-login-api
ex) be/feat-common-component

• 개인 작업

feat#이슈번호  
  
ex) feat#123
ex) feat#456

브랜치 사용 흐름 예시

main                ← 배포용 (완전 안정)
└─ dev              ← 공용 개발 브랜치
    ├─ fe/feat-login-api
    └─ be/feat-common-component ← 기능 브랜치
                  ├─ feat#123     ← 개인 작업 브랜치
                  └─ feat#125     ← 개인 작업 브랜치

브랜치 권한

• main
  • 최소 2명이상 승인해야 Merge 가능
• dev
  • 최소 1명이상 승인해야 Merge 가능
• 파트명/feat-기능명
  • 최소 1명이상 승인해야 Merge 가능

---

3️⃣ 이슈 템플릿

기능 개발

name: "💡 Feat"
description: "새로운 기능 추가 템플릿"
title: "[Feat] "
labels: "feat"
body:
  - type: textarea
    attributes:
      label: 📝 설명
      description: 새로운 기능에 대해 설명해주세요.
      placeholder: 기능에 대해서 적어주세요.
    validations:
      required: true
  - type: textarea
    attributes:
      label: ✅ 체크사항
      description: 주어진 기능에 대해서 체크박스를 만들어주세요.
      placeholder: 기능에 대해서 나열해주세요.
    validations:
      required: true

버그 수정

name: "🛠️ Fix"
description: "Fix 템플릿"
title: "[Fix] "
labels: "fix"
body:
  - type: textarea
    attributes:
      label: 🐞 버그 설명
      description: 버그에 대한 설명을 작성해 주세요.
    validations:
      required: true
  - type: textarea
    attributes:
      label: 🧾 로그
      description: 로그가 있으면 복붙해 주세요.
      render: shell
    validations:
      required: false

리펙토링

name: "♻️ Refactor"
description: "리팩토링 템플릿"
title: "[Refactor] "
labels: "refactor"
body:
  - type: textarea
    attributes:
      label: ❓ 이유
      description: 리팩토링을 진행한 이유를 설명해주세요.
    validations:
      required: true
  - type: textarea
    attributes:
      label: ✅ 수정
      description: 수정한 부분을 적어주세요.
    validations:
      required: true

4️⃣ PR 템플릿

## #️⃣ Issue Number


## 🕹️ 작업 내용

한 줄 요약 : 
- [ ]
- [ ]

## 📋 리뷰 포인트

-
-

## 🔮 기타 사항

-
-