Kickytime – 브랜치 전략, 커밋 규칙, CI/CD 품질 관리 (프로젝트 협업)

0. 들어가며

Kickytime 프로젝트는 5명이 함께한 2주 단기 협업 프로젝트였습니다. 제한된 시간 안에서도 효율적이고 일관된 협업을 하기 위해 브랜치 전략, 커밋 메시지 규칙, 코드 품질 도구, 이슈/PR 템플릿을 체계적으로 적용했습니다. 이번 글에서는 협업 문화를 어떻게 설계하고 실천했는지를 기록합니다.

---

1. 브랜치 전략 – GitLab Flow 기반 단순 구조

1-1. 브랜치 구조

브랜치	설명
main	운영 환경(Production) 배포용
develop	개발 통합 브랜치, 기능 병합 전 테스트 공간
feature/*	기능별 브랜치 (feature/이슈번호-간단설명)
hotfix/*	운영 중 발생한 긴급 수정 브랜치

1-2. 운영 규칙

• main, develop은 보호 브랜치로 설정 → 직접 푸시 금지
• 모든 변경은 PR(Pull Request)을 통해 병합, 최소 1명 리뷰 승인 필수

• 브랜치 네이밍 예시:

  • feature/123-user-login
  • hotfix/456-admin-crash

1-3. 브랜치 생명주기

• feature/*: PR 병합 후 즉시 삭제 (중복 방지)
• hotfix/*: 긴급 수정 후 main + develop 모두에 병합, 병합 완료 후 삭제
• develop: 항상 빌드 가능한 상태 유지

짧은 프로젝트였지만, 브랜치 정책을 엄격히 지키면서 충돌 최소화 + 안정적인 병합을 경험할 수 있었습니다.

---

2. 커밋 메시지 규칙 – Conventional Commits + Gitmoji

2-1. 형식

<이모지> <타입>(선택적 scope): <커밋 메시지>

본문(선택)

2-2. 타입 & 이모지 규칙 (발췌)

이모지	타입	예시	설명
✨	feat	✨ feat(auth): 사용자 대시보드 페이지 추가	새로운 기능
🐛	fix	🐛 fix(login): 로그인 실패 예외 처리	버그 수정
♻️	refactor	♻️ refactor: 중복 조건문 제거	구조 개선
📄	docs	📄 docs: 배포 방법 문서 추가	문서 변경
🏗️	setup	🏗️ setup: Spring Boot 초기 설정	프로젝트 세팅
📦	chore	📦 chore: 라이브러리 버전 정리	유지보수

2-3. 커밋 단위 원칙

• 하나의 커밋 = 하나의 논리적 변경
• 기능 추가, 버그 수정, 리팩토링을 최대한 분리
• 관련 없는 변경은 한 커밋에 묶지 않음 → 리뷰·롤백 용이

Gitmoji를 쓰니 커밋 로그만 봐도 변경 성격을 직관적으로 파악할 수 있었고, 팀원들 모두 재미있게 규칙을 지킬 수 있었습니다.

---

3. 버전 관리 – Semantic Versioning

3-1. 태그 규칙

• 태그 형식: vMAJOR.MINOR.PATCH
• 예시: v1.0.0, v1.2.3

3-2. 증가 규칙

구분	설명	예시
MAJOR	호환 불가 변경 발생	v1.1.1 → v2.0.0
MINOR	새로운 기능 (호환성 유지)	v1.0.0 → v1.1.0
PATCH	버그 수정 (호환성 유지)	v1.1.0 → v1.1.1

3-3. 관리 원칙

1. 배포 시점에만 태그 부여 (중간 개발 단계는 태그 X)
2. 태그 푸시 시 GitHub Releases에 자동 연동
3. 프리릴리즈/핫픽스 예외: v1.0.0-beta.1, v1.0.1-hotfix.1

---

4. 코드 품질 도구 – FE/BE 일관된 자동화

4-1. Frontend (React + TS)

• Prettier: 포맷팅
• ESLint: 린트 검사
• Commitlint: 커밋 메시지 검사
• Husky + lint-staged: Git Hooks → 변경 파일만 검사

4-2. Backend (Spring Boot + Java)

• Spotless: Java 코드 포맷팅
• Checkstyle: 스타일·네이밍 규칙 검사
• Commitlint: FE와 동일 규칙 적용
• Gradle Task 연계: check 시 자동 실행

4-3. Git Hooks 동작 요약

• pre-commit: FE 린트+포맷 / BE 포맷+체크스타일
• commit-msg: 모든 커밋 메시지 규칙 검사

4-4. CI 연계

• FE: GitHub Actions에서 npm run lint + format:check
• BE: GitHub Actions에서 ./gradlew spotlessCheck checkstyleMain
• 실패 시 → PR 병합 차단

로컬 훅과 CI가 함께 작동해 “어디서든 동일한 규칙”을 보장했습니다.

---

5. 이슈 & PR 템플릿 – 협업 효율 강화

5-1. 이슈 템플릿 종류

• 기능 요청: feature_request.yml
• 버그 리포트: bug_report.yml
• 문서 변경: documentation.yml
• 일반 작업: task.yml

→ 이슈 생성 시 누락 없는 양식을 보장, 라벨 자동 지정

5-2. PR 템플릿 규칙

• 섹션 구성: 개요 → 변경 사항 → 테스트 방법 → 체크리스트 → 참고 이슈
• 최소 1명 리뷰 승인 후 병합

---

6. 회고

짧은 기간이었지만, 협업 문화를 정비하면서 다음과 같은 생각을 가졌습니다:

• 규칙이 있으면 의사결정이 단순해지고, 모두가 같은 기준으로 작업 가능
• Gitmoji + Conventional Commit은 팀 전체에 긍정적 동기 부여를 줌
• CI 연계 덕분에 “실수해도 규칙이 지켜진다”는 신뢰 확보

결과적으로 협업 방식 자체가 팀 학습 효과로 이어졌고, 단기 프로젝트임에도 불구하고 실무에 가까운 개발 문화를 체험할 수 있었습니다.