Conventional Commits: 협업을 위한 커밋 메시지 표준화 전략

개발 프로젝트에서 동료들의 커밋 메시지를 이해하기 어려웠던 경험이 있으신가요? 혹은 여러 달 전에 자신이 작성한 코드를 다시 살펴볼 때 커밋 메시지만으로는 어떤 변경이 이루어졌는지 파악하기 힘들었던 적이 있으신가요? Conventional Commits는 이런 문제를 해결하는 효과적인 방법입니다.

---

Conventional Commits란?

Conventional Commits는 커밋 메시지를 구조화된 형식으로 작성하기 위한 규칙입니다. 이 규칙은 Angular 팀에서 처음 도입한 커밋 메시지 형식에서 영감을 받았으며, 현재는 많은 개발팀과 오픈 소스 프로젝트에서 널리 사용되고 있습니다.

기본 구조는 다음과 같습니다:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

예를 들면 다음과 같습니다:

feat(auth): 소셜 로그인 기능 추가

- Google, Facebook 로그인 구현
- 로그인 후 사용자 정보 저장 로직 개선

Closes #123

---

Conventional Commits 주요 접두사 (Type)

Conventional Commits의 핵심은 커밋 메시지 앞에 붙는 "타입(type)"입니다. 각 타입은 해당 커밋이 어떤 종류의 변경인지를 명확하게 표현합니다.

타입	설명	예시
feat	새로운 기능 추가	feat: 사용자 프로필 이미지 업로드 기능 추가
fix	버그 수정	fix: 모바일에서 메뉴가 표시되지 않는 문제 해결
docs	문서 수정	docs: README 파일 업데이트
style	코드 스타일 변경 (코드 포맷팅, 세미콜론 누락 등)	style: 들여쓰기 2칸으로 통일
refactor	성능 개선이나 버그 수정이 아닌 코드 리팩토링	refactor: 사용자 인증 로직 리팩토링
test	테스트 코드 추가 또는 수정	test: 회원가입 API 테스트 케이스 추가
chore	빌드 프로세스, 라이브러리 설치 등 기타 변경사항	chore: package.json 의존성 업데이트
ci	CI 설정 파일 및 스크립트 변경	ci: GitHub Actions 워크플로우 수정
perf	성능 개선 코드	perf: 이미지 로딩 속도 최적화

또한 필요에 따라 다음과 같은 타입을 추가로 사용할 수 있습니다:

타입	설명
build	빌드 시스템 또는 외부 종속성 관련 변경
revert	이전 커밋을 되돌릴 때
wip	작업 진행 중(Work In Progress)

---

협업에서 Conventional Commits를 사용해야 하는 이유

1. 명확한 변경 이력 관리

커밋 메시지를 표준화하면 어떤 변경이 이루어졌는지 한눈에 파악할 수 있습니다. 코드 리뷰 시간이 단축되고, 버전 관리가 용이해집니다.

$ git log --oneline
a1b2c3d feat(auth): 소셜 로그인 기능 추가
e4f5g6h fix(ui): 모바일 뷰 레이아웃 깨짐 수정
i7j8k9l docs: API 문서화 추가

위 로그만 봐도 어떤 변경이 있었는지 즉시 이해할 수 있습니다.

2. 자동화된 버전 관리 및 릴리스 노트 생성

Conventional Commits는 Semantic Versioning(SemVer)과 잘 어울립니다. 커밋 타입에 따라 자동으로 버전 번호를 증가시킬 수 있습니다:

• feat: minor 버전 증가 (1.0.0 → 1.1.0)
• fix: patch 버전 증가 (1.0.0 → 1.0.1)
• feat! 또는 BREAKING CHANGE: major 버전 증가 (1.0.0 → 2.0.0)

또한 standard-version이나 semantic-release 같은 도구를 사용하면 커밋 메시지를 기반으로 자동으로 CHANGELOG.md 파일을 생성할 수 있습니다.

3. 팀 내 의사소통 개선

모든 팀원이 동일한 규칙으로 커밋 메시지를 작성하면 코드베이스 변경에 관한 의사소통이 명확해집니다. 이는 특히 원격 근무 환경이나 여러 시간대에 걸쳐 작업하는 팀에서 더욱 중요합니다.

4. 새로운 개발자의 온보딩 간소화

새로운 팀원이 프로젝트에 합류했을 때, 구조화된 커밋 메시지는 코드베이스의 역사와 개발 방향을 빠르게 이해하는 데 도움이 됩니다.

5. 통계 및 분석 용이

커밋 타입이 표준화되어 있다면 다음과 같은 분석이 가능합니다:

# 버그 수정이 얼마나 많았는지 확인
$ git log --oneline | grep "^fix" | wc -l

# 기능 추가가 많았던 기간 확인
$ git log --after="2023-01-01" --before="2023-06-30" --oneline | grep "^feat" | wc -l

이를 통해 프로젝트의 건강 상태나 개발 주기에 대한 통찰력을 얻을 수 있습니다.

---

Conventional Commits 실전 적용 방법

실제 예시로 보는 Conventional Commits

아래는 실제 개발 과정에서 사용할 수 있는 Conventional Commits 예시입니다:

feat(auth): 이메일 인증 기능 추가

회원가입 시 이메일 인증 절차를 추가하여 보안 강화
- 인증 코드 생성 및 이메일 발송 기능
- 인증 코드 확인 및 계정 활성화 기능

Closes #42

fix(api): 사용자 프로필 업데이트 시 500 에러 해결

프로필 이미지 URL이 null일 때 발생하는 NullPointerException 처리

Fixes #78

도구를 활용한 규칙 강제화

팀 프로젝트에서 Conventional Commits를 일관되게 적용하기 위해 다음과 같은 도구를 활용할 수 있습니다:

1. commitlint: 커밋 메시지가 규칙을 따르는지 검사

# 설치
npm install -g @commitlint/cli @commitlint/config-conventional

# 설정 파일 생성
echo "module.exports = {extends: ['@commitlint/config-conventional']}" > commitlint.config.js

2. husky: Git 훅을 사용해 커밋 전 규칙 검사 자동화

# 설치
npm install -D husky

# Git 훅 설정
npx husky install
npx husky add .husky/commit-msg 'npx --no -- commitlint --edit "$1"'

3. commitizen: 대화형 커밋 메시지 작성 도구

# 설치
npm install -g commitizen
npm install -D cz-conventional-changelog

# 설정
echo '{ "path": "cz-conventional-changelog" }' > .czrc

이후 git commit 대신 git cz 명령어를 사용하면 대화형으로 커밋 메시지를 작성할 수 있습니다.

---

실무에서의 Conventional Commits 도입 전략

점진적 도입

기존 프로젝트에 Conventional Commits를 도입할 때는 점진적으로 적용하는 것이 좋습니다:

1. 팀 내 규칙 합의 및 문서화
2. 파일럿 기간 설정 (1-2주)
3. 피드백 수렴 및 조정
4. 전체 프로젝트에 적용

커스텀 타입 정의

프로젝트의 특성에 맞게 추가 타입을 정의할 수 있습니다:

i18n: 국제화/현지화 관련 변경
security: 보안 이슈 수정
design: UI/UX 디자인 변경

Git 브랜치 전략과의 통합

Conventional Commits는 Git-Flow나 GitHub Flow 같은 브랜치 전략과 함께 사용할 때 더욱 효과적입니다. 예를 들어, feature 브랜치에서 작업할 때는 해당 기능에 관련된 커밋 메시지를 일관되게 유지할 수 있습니다.

# feature/user-profile 브랜치
feat(profile): 프로필 이미지 업로드 기능 추가
feat(profile): 프로필 정보 수정 폼 개선
test(profile): 프로필 업데이트 테스트 케이스 추가

---

결론

Conventional Commits는 단순한 커밋 메시지 형식 이상의 가치를 제공합니다. 이는 팀 협업의 효율성을 높이고, 코드베이스의 유지보수성을 개선하며, 자동화된 버전 관리와 문서화를 가능하게 합니다.

특히 팀의 규모가 커지거나 오픈소스 프로젝트에서는 명확한 커뮤니케이션이 프로젝트의 성공에 필수적입니다. Conventional Commits는 이러한 명확한 커뮤니케이션을 위한 효과적인 도구입니다.

코드 자체만큼이나 그 코드의 변경 이력 관리도 중요합니다. Conventional Commits를 도입하여 더 체계적이고 효율적인 개발 문화를 만들어보세요.

---

참고 자료

• Conventional Commits 공식 웹사이트
• Angular Commit Message Guidelines
• Semantic Versioning
• commitlint
• husky
• commitizen