4.9 KiB
4.9 KiB
Git 커밋 컨벤션
업데이트: 2025-12-02
커밋 메시지 형식
[타입]: [scope] 작업내용
- 세부항목 (생략가능)
- 세부항목 2
Issue: URL (생략가능)
예시
feat: [calendar] 달력 기능 개선
- 클릭시 오류 기능 개선
- 색상 변경
- 각 항목별 색상 지정
Issue: https://www.notion.so/hamss/2269c8d34ba080489680e0607a95d9c4
fix: [auth] 로그인 시 세션 만료 오류 수정
refactor: [user] UserService 메서드 분리
- validateUser 메서드 추출
- 중복 코드 제거
Commit Types
| Type | 설명 | 예시 |
|---|---|---|
feat |
새로운 기능 추가 | feat: [file] 파일 업로드 기능 추가 |
fix |
버그 수정 | fix: [auth] 세션 만료 오류 수정 |
chore |
설정, 빌드 등 변경 | chore: composer 패키지 업데이트 |
refactor |
프로덕션 코드 리팩토링 | refactor: [user] 서비스 메서드 분리 |
style |
포맷/코딩 스타일 수정 | style: Pint 포맷팅 적용 |
test |
테스트 추가/수정 | test: Product API 테스트 추가 |
docs |
문서 변경 | docs: API 문서 업데이트 |
fix vs feat vs refactor 판단 기준
"고치는 작업"이 많으므로 타입 선택 시 다음 기준을 따른다:
| 상황 | 타입 | 핵심 기준 |
|---|---|---|
| 기존 기능이 의도대로 동작하지 않는 것을 수정 | fix |
원래 되어야 하는데 안 되는 것 |
| 계산 결과가 틀림, 데이터가 누락됨, 에러 발생 | fix |
기대 결과와 실제 결과가 다름 |
| 기존 기능에 새 조건/필터/옵션을 추가 | feat |
없던 것을 새로 만드는 것 |
| 요청에 의한 동작 변경 (사양 변경) | feat |
버그가 아닌 새로운 요구사항 |
| 동작은 동일, 코드 구조만 개선 | refactor |
결과는 같고 내부만 변경 |
| 설정 파일, 의존성, 빌드 변경 | chore |
코드 동작과 무관한 관리 작업 |
✅ fix = "깨진 것을 고친다" (버그, 오류, 잘못된 결과)
✅ feat = "없던 것을 만든다" (신규 기능, 사양 변경, 기능 확장)
✅ refactor = "같은 것을 더 좋게 만든다" (구조 개선, 중복 제거)
커밋 빈도 가이드
원칙: "논리적 단위"로 커밋
❌ 파일 하나 수정할 때마다 커밋 (너무 잦음)
❌ 몇 시간 작업을 한 번에 커밋 (되돌리기 어려움)
✅ 하나의 의미 있는 변경이 완성되면 커밋
"의미 있는 변경" 기준
- 마이그레이션 1건 완성
- Service/Controller 로직 수정 1건 완성
- Swagger 문서 업데이트 완성
- 설정 파일 변경 완성
예시 — WorkOrder API 수정 작업
# 1) DB 변경 완성 → 커밋
fix: [work-order] options 컬럼 추가 마이그레이션
# 2) 비즈니스 로직 완성 → 커밋
fix: [work-order] 옵션 필터링 로직 수정
# 3) 문서 업데이트 → 커밋
docs: [work-order] options 파라미터 Swagger 추가
장점
- 되돌리기 용이: 마이그레이션만, 로직만, 문서만 선택적 revert 가능
- 코드 리뷰 용이: 커밋 단위로 변경 의도 파악 가능
- 작업 손실 방지: 중간에 문제 발생 시 이전 커밋까지 안전
Claude 서명 제외 정책
커밋 메시지에 다음 내용을 포함하지 않음:
❌ 🤖 Generated with [Claude Code](https://claude.com/claude-code)
❌ Co-Authored-By: Claude <noreply@anthropic.com>
- Git hooks로 자동 제거됨
- 간결하고 명확한 한글 커밋 메시지만 유지
저장소별 커밋
# 각 저장소에서 개별 커밋
cd api && git add . && git commit -m "feat: [scope] 작업 내용"
cd ../mng && git add . && git commit -m "feat: [scope] 작업 내용"
cd ../react && git add . && git commit -m "feat: [scope] 작업 내용"
Branch 전략
Feature Development
# main/master에서 직접 작업 금지
git checkout -b feature/file-storage-system
# 작업 진행...
git commit -m "feat: [file] ..."
# PR 생성
Hotfix
git checkout -b hotfix/login-session-bug
# 긴급 수정...
git commit -m "fix: [auth] ..."
# PR 또는 즉시 병합
커밋 전 체크리스트
✓ ./vendor/bin/pint 실행 (코드 포맷팅)
✓ php artisan migrate:status 확인
✓ 테스트 실행 (해당하는 경우)
✓ git diff 로 변경사항 검토
✓ 불필요한 파일 제외 (.env, node_modules 등)
✓ CURRENT_WORKS.md 업데이트
푸시 정책
- 사용자가 수동으로 푸시 진행
- 자동 푸시 하지 않음
- 커밋 후 푸시 여부를 묻지 않음
중요 사항
- 각 저장소는 독립적으로 운영
- 저장소별 개별 커밋 메시지 사용
- 일관된 커밋 타입 및 형식 유지
관련 문서
최종 업데이트: 2025-12-02