형상관리

23.1. GitHub Flow 브랜치 전략

23.1.1. 기본 원칙

• main 브랜치는 항상 배포 가능한 상태를 유지합니다.
• 모든 작업은 main에서 분기한 feature 브랜치에서 수행합니다.
• 작업 완료 후 Pull Request를 생성하고, 리뷰를 거쳐 main에 머지합니다.

23.1.2. 브랜치 네이밍

접두사	용도	예시
feature/	새로운 기능 개발	feature/user-registration
fix/	버그 수정	fix/login-redirect-error
hotfix/	프로덕션 긴급 수정	hotfix/payment-null-check
chore/	빌드, 설정, 의존성 등 비기능 작업	chore/update-spring-boot
docs/	문서 작업	docs/api-specification
refactor/	리팩토링	refactor/user-service-cleanup

23.1.3. 브랜치 네이밍 규칙

• 소문자와 하이픈(-)만 사용합니다.
• 슬래시(/)는 접두사 구분에만 사용합니다.
• 브랜치명은 작업 내용을 간결하게 설명합니다.
• 이슈 번호가 있는 경우 포함합니다: feature/123-user-registration

23.1.4. 워크플로우

---

23.2. 커밋 메시지 컨벤션

23.2.1. Conventional Commits

모든 커밋 메시지는 Conventional Commits 형식을 따릅니다.

<type>: <description>

[optional body]

23.2.2. 타입 목록

타입	설명	예시
feat	새로운 기능	feat: 사용자 프로필 조회 API 추가
fix	버그 수정	fix: 로그인 시 리다이렉트 오류 수정
docs	문서 변경	docs: API 명세서 업데이트
style	코드 포매팅 (동작 변경 없음)	style: import 정렬
refactor	리팩토링 (동작 변경 없음)	refactor: UserService 메서드 추출
test	테스트 추가/수정	test: UserService 단위 테스트 추가
chore	빌드, 설정 변경	chore: Spring Boot 3.4.3 업데이트
perf	성능 개선	perf: 사용자 목록 쿼리 최적화
ci	CI 설정 변경	ci: CircleCI 캐시 설정 추가

23.2.3. 커밋 메시지 규칙

• 제목은 50자 이내로 작성합니다.
• 제목은 명령형으로 작성합니다. ("추가한다" X → "추가" O)
• 제목 끝에 마침표를 붙이지 않습니다.
• 본문이 필요한 경우 제목과 빈 줄로 구분합니다.
• 한글 또는 영문 중 프로젝트별로 통일합니다.

---

23.3. Pull Request 규칙

23.3.1. PR 필수 조건

항목	기준
리뷰어	최소 1명 이상의 승인
CI	모든 체크 통과 (린트, 빌드, 테스트)
충돌	머지 충돌 해소 완료
브랜치	main 대비 최신 상태

23.3.2. PR 템플릿

프로젝트에 .github/pull_request_template.md를 포함합니다.

## 변경 사항
<!-- 이 PR에서 변경한 내용을 간략히 설명합니다 -->

## 변경 사유
<!-- 왜 이 변경이 필요한지 설명합니다 -->

## 테스트
- [ ] 단위 테스트 추가/수정
- [ ] 로컬에서 동작 확인

## 관련 이슈
<!-- 관련 이슈 번호 (예: #123) -->

23.3.3. 머지 전략

• Squash and Merge를 기본으로 사용합니다.
• 머지 후 feature 브랜치는 자동으로 삭제합니다.

---

23.4. .gitignore 표준

23.4.1. 통합 .gitignore 예시

# Java / Maven
target/
*.class
*.jar
*.war

# Spring Boot
*.log

# IDE
.idea/
*.iml
.vscode/*
!.vscode/settings.json
!.vscode/extensions.json

# Node.js
node_modules/
dist/

# 환경변수
.env.local
.env.*.local

# OS
.DS_Store
Thumbs.db

23.4.2. 원칙

• 빌드 산출물(target/, dist/)은 추적하지 않습니다.
• IDE 설정 중 팀 공유 설정(.vscode/settings.json)만 추적합니다.
• 로컬 환경변수(.env.local)는 추적하지 않습니다.

---

23.5. 버전 태깅

23.5.1. Semantic Versioning

모든 릴리스는 Semantic Versioning (SemVer) 규칙을 따릅니다.

MAJOR.MINOR.PATCH

구분	변경 시점	예시
MAJOR	하위 호환성이 깨지는 변경	1.0.0 → 2.0.0
MINOR	하위 호환되는 기능 추가	1.0.0 → 1.1.0
PATCH	하위 호환되는 버그 수정	1.0.0 → 1.0.1

23.5.2. 태그 형식

• Git 태그 형식: v{MAJOR}.{MINOR}.{PATCH}
• 예시: v1.0.0, v1.2.3

git tag -a v1.0.0 -m "v1.0.0 릴리스"
git push origin v1.0.0

23.5.3. 릴리스 노트

모든 릴리스에는 변경 사항을 기술한 릴리스 노트를 작성합니다. 커밋 메시지의 타입별로 그룹핑하여 작성합니다.