Git

[Git] Conventional Commits: 9가지 규칙으로 팀 협업 강화하기

MayQ 2025. 6. 3. 21:44

개요

Git에서 커밋 메시지는 팀 간의 소통을 원활히 하고 프로젝트의 히스토리를 관리하는 데 중요한 역할을 합니다. 하지만 협업 프로젝트에서는 다양한 커밋 메시지 스타일로 인해 혼란이 발생할 수 있습니다. Conventional Commits는 이러한 문제를 해결하기 위해 일관된 규칙을 제공합니다. 이를 통해 커밋 메시지가 명확하게 구조화되며, 자동화된 릴리스 및 CHANGELOG 생성과 같은 작업을 효율적으로 처리할 수 있습니다​.

예를 들어, 프로젝트가 커지면서 코드가 복잡해질수록 변경 사항을 파악하는 것이 어려워집니다. Conventional Commits는 커밋 메시지에 일관성을 부여하여 변경 사항을 쉽게 추적할 수 있게 도와줍니다. 이렇게 체계적으로 관리된 커밋 히스토리는 팀 내 소통을 강화할 뿐만 아니라, 자동화 도구와의 연동을 통해 릴리스 프로세스를 간소화할 수 있습니다.

Conventional Commits 형식

Conventional Commits 메시지는 다음과 같은 형식을 따릅니다:

<type>(<scope>): <description>
  • type: 커밋의 유형을 나타내는 필수 항목입니다.
  • scope: 선택적 항목으로, 변경된 코드의 범위를 명시합니다.
  • description: 변경 사항을 간결하게 설명합니다.

이 형식은 커밋 메시지를 읽는 사람이 어떤 목적의 변경인지 한눈에 파악할 수 있도록 도와줍니다. type은 주요 카테고리로 나뉘며, 예를 들어 feat는 새로운 기능 추가, fix는 버그 수정을 의미합니다. scope는 코드베이스의 특정 부분을 명확히 할 때 사용합니다. 예를 들어 feat(auth):는 인증 관련 기능 추가를 의미합니다.

주요 커밋 타입과 사용 사례

Conventional Commits에서 자주 사용되는 커밋 타입은 다음과 같습니다:

feat

새로운 기능을 추가할 때 사용합니다. 이 커밋 타입은 프로젝트 히스토리에서 기능이 언제 추가되었는지 명확히 파악할 수 있어 이후 유지보수에 큰 도움이 됩니다. 새로운 기능이 도입될 때마다 feat 커밋이 사용되므로, 프로젝트의 성장을 한눈에 볼 수 있습니다.

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

fix

버그를 수정할 때 사용합니다. 이는 대부분의 프로젝트에서 빈번하게 발생하는 작업이며, 명확한 fix 커밋은 문제 해결 과정을 기록하고 추후 버그가 재발했을 때 분석하는 데 유용합니다. 이렇게 명시된 커밋은 버그 수정 히스토리를 쉽게 추적할 수 있게 합니다.

예: fix(cart): 장바구니 삭제 기능 오류 수정

docs

문서만 수정할 때 사용됩니다. 코드에는 영향을 미치지 않고, README 파일, 개발 가이드 또는 기타 문서 파일을 업데이트할 때 적합한 커밋 타입입니다. 문서 변경은 코드 기능에 대한 변화가 없으므로 독립적으로 구분하는 것이 좋습니다.

예: docs(readme): 설치 가이드 업데이트

style

코드의 기능에 영향을 미치지 않는 형식적 변경 사항을 기록할 때 사용합니다. 예를 들어 들여쓰기 수정, 공백 추가, 세미콜론 삽입 등 코드의 의미를 변경하지 않는 작업이 여기에 해당됩니다. 이를 통해 코드를 더 깔끔하고 일관되게 유지할 수 있습니다.

예: style(global): 들여쓰기 규칙 통일

refactor

코드의 기능은 변경하지 않으면서 내부 구조를 개선하는 작업을 기록할 때 사용합니다. 리팩토링은 코드의 유지보수성과 가독성을 향상시키며, 새로운 기능 추가나 버그 수정과는 다릅니다. 리팩토링 작업은 장기적으로 코드 품질을 향상시키는 데 중점을 둡니다.

예: refactor(user-service): 유저 데이터 처리 로직 최적화

test

테스트 코드를 추가하거나 수정할 때 사용됩니다. 새로운 기능에 대한 테스트 작성, 기존 테스트 케이스 수정, 또는 테스트 범위를 확장하는 작업이 해당됩니다. 테스트 커밋을 명확히 구분하면 코드 품질을 유지하고, 문제 발생 시 더 쉽게 디버깅할 수 있습니다.

예: test(auth): 로그인 기능 테스트 추가

chore

빌드 프로세스, 도구 설정, 패키지 관리 등과 같이 코드 변경과는 무관한 작업을 기록할 때 사용합니다. 예를 들어 의존성 업데이트나 설정 파일 변경, CI/CD 설정 변경 등이 해당됩니다. chore 커밋은 기능 추가나 버그 수정과는 관련이 없지만, 프로젝트 유지보수에 중요한 역할을 합니다.

예: chore(build): 의존성 패키지 업데이트

perf

성능 개선을 위한 코드 변경 시 사용됩니다. 예를 들어 페이지 로딩 속도를 개선하거나 메모리 사용량을 줄이는 작업이 해당됩니다. 성능 최적화 커밋을 perf로 명시하면, 성능과 관련된 변경 사항을 손쉽게 추적할 수 있습니다.

예: perf(images): 이미지 로딩 속도 개선

Body와 Footer 작성

Body

커밋의 본문(Body)은 변경 사항을 더 상세히 설명할 때 사용됩니다. 예를 들어, 코드 변경이 복잡하거나 여러 개의 작업이 한 커밋에 포함된 경우, 본문을 통해 변경 사항의 목적과 배경을 설명하는 것이 좋습니다. 커밋 메시지의 본문은 커밋 제목 아래에 위치하며, 여러 문단으로 나눌 수 있습니다.

Footer

Footer는 중요한 변경 사항이나 관련된 이슈 번호를 명시할 때 사용됩니다. 특히 BREAKING CHANGE가 발생한 경우, Footer에 명확히 기록하여 해당 커밋이 기존 시스템에 어떤 영향을 미치는지 알릴 수 있습니다.

BREAKING CHANGE: 데이터베이스 스키마가 변경되어 이전 버전과 호환되지 않습니다.

Conventional Commits의 장점

Conventional Commits는 단순한 규칙이지만, 프로젝트 관리에 많은 이점을 제공합니다:

  • 자동화 지원: Conventional Commits는 릴리스 자동화 도구와의 통합을 쉽게 해줍니다. 예를 들어, 커밋 타입에 따라 자동으로 버전이 업데이트되거나 CHANGELOG가 생성됩니다.
  • 일관성: 커밋 메시지의 일관성은 팀 내 커뮤니케이션을 원활하게 하고, 코드 리뷰를 더욱 효율적으로 진행할 수 있게 도와줍니다.
  • 변경 내역 추적: 각 커밋이 어떤 작업을 했는지 명확하게 구분되므로, 특정 기능이나 버그 수정이 언제, 어떻게 이루어졌는지 쉽게 추적할 수 있습니다.

Conventional Commits 적용 예시

Conventional Commits를 실제로 프로젝트에 적용하는 방법은 간단합니다. 예를 들어, GitHub에서 커밋 메시지를 작성할 때 다음과 같은 형식을 사용할 수 있습니다:

  • 새로운 기능 추가 시
git commit -m "feat(api): 사용자 로그인 기능 추가"
  • 호환성을 깨는 변경 사항이 있을 경우
git commit -m "feat!: API 인증 방식 변경"
BREAKING CHANGE: 인증 방식이 토큰 기반으로 변경되었습니다.

이처럼 일관된 커밋 메시지를 사용하면, 팀 전체가 쉽게 변경 사항을 이해하고 관리할 수 있습니다.

결론

Conventional Commits는 커밋 메시지 작성에 대한 명확하고 일관된 가이드를 제공하여, 협업을 더욱 효율적이고 체계적으로 만들어 줍니다. 이러한 커밋 메시지 규칙을 준수하면, 팀 구성원 간에 변경 사항을 쉽게 이해할 수 있을 뿐만 아니라, 프로젝트 관리와 유지 보수에 큰 도움이 됩니다.

  1. 프로젝트 유지 보수성 향상
    • 프로젝트가 장기화되거나 여러 개발자가 참여할 경우, 커밋 메시지가 일관되게 관리되지 않으면, 어떤 변경 사항이 있었는지 파악하기 어렵습니다. Conventional Commits를 적용하면 각 커밋의 목적과 내용이 명확해져 변경 내역을 추적하기가 쉬워지고, 후속 작업이나 버그 수정을 위한 참고 자료로 유용합니다. 특히, 버그나 특정 기능의 도입 시점을 쉽게 확인할 수 있어, 코드 유지 보수 작업이 훨씬 수월해집니다​.
  2. 릴리스 프로세스 간소화
    • Conventional Commits는 릴리스 자동화와의 자연스러운 통합을 지원합니다. 예를 들어, semantic versioning과 결합하여 커밋 메시지에 따라 자동으로 버전이 결정되고, CHANGELOG가 생성됩니다. 이는 릴리스 주기를 빠르고 정확하게 관리할 수 있도록 돕습니다. 특히, feat(새 기능 추가)나 fix(버그 수정) 같은 명확한 커밋 타입 덕분에, 릴리스 관리자는 어떤 변경 사항이 릴리스에 포함되어야 하는지 쉽게 알 수 있습니다​.
  3. 개발 효율성 향상
    • Conventional Commits는 개발자의 작업을 보다 구조적으로 만들며, 커밋 메시지 자체가 코드 변경에 대한 문서 역할을 하게 됩니다. 코드 리뷰 시, 일관된 메시지를 통해 어떤 변경이 있었는지 쉽게 파악할 수 있고, 팀 내 다른 개발자들도 각각의 커밋이 어떤 목적을 가지고 작성되었는지 명확하게 알 수 있습니다. 이렇게 명료한 구조 덕분에, 새로운 개발자가 프로젝트에 참여해도 빠르게 적응할 수 있으며, 전체 팀의 개발 속도와 효율이 향상됩니다.

표 요약

아래 표는 Conventional Commits에서 자주 사용되는 주요 키워드와 그 설명을 요약한 것입니다.

키워드설명예시

feat 새로운 기능을 추가할 때 사용 feat(auth): 소셜 로그인 기능 추가
fix 버그 수정 시 사용 fix(api): 로그인 오류 수정
docs 문서 수정 (코드 변경 없음) docs(readme): 설치 가이드 업데이트
style 코드 형식이나 포맷 변경 (기능 변화 없음) style(global): 들여쓰기 규칙 통일
refactor 코드 리팩토링, 기능 추가나 버그 수정이 아님 refactor(user-service): 로직 최적화
test 테스트 코드 추가 또는 수정 test(api): 인증 기능 테스트 추가
chore 빌드 프로세스 변경, 패키지 업데이트 등 코드와 직접 관련 없는 작업 chore(build): 의존성 패키지 업데이트
perf 성능을 개선하기 위한 코드 변경 perf(images): 이미지 로딩 속도 개선
BREAKING CHANGE 호환성을 깨는 변경 사항을 설명하는 데 사용 BREAKING CHANGE: 스키마가 변경되었습니다.