Conventional Commits

Conventional Commits

Conventional Commits 는 버전 관리 시스템 (Version Control System, VCS) 의 커밋 메시지를 일관성 있게 작성하기 위한 규약입니다. 이를통해 팀 내에서 일관성 있는 커밋 메시지 작성이 가능해지고 가독성이 향상되며 릴리즈 관리, 버전 관리 등의 프로세스를 자동화할 수 있습니다.

Conventional Commits 메시지 구조

<type>(<scope>): <description> ← 이 전체가 header

[optional body]

[optional footer]

# header 만 있든, body 까지 있든, footer 까지 있든, 마지막 줄에는 공백 없이 끝내는 것이 일반적

• <type>: 커밋이 수행한 작업의 종류를 나타냅니다. 주요 타입은 다음과 같습니다.
  • feat: 새로운 기능 추가
  • fix: 버그 수정
  • docs: 문서 변경
  • style: 코드 스타일 변경 (코드 포맷팅, 세미콜론 추가 등)
  • refactor: 코드 리팩토링 (기능 변경 없음)
  • perf: 성능 개선
  • test: 테스트 코드 추가 또는 수정
  • chore: 기타 변경 (빌드, 설정 파일 등)
• <scope> (선택 사항): 변경 사항이 영향을 미친 범위나 모듈을 나타냅니다. 예를 들어, ui, api, auth 등이 될 수 있습니다.
• <description>: 커밋의 주요 변경 사항을 보통 50자 이내로 간결하고 명확하게 설명합니다.
• [optional body] (선택 사항): 커밋에 대해 추가적인 설명이 필요할 경우 작성합니다.
• [optional footer] (선택 사항): 커밋에 관련된 이슈 트래킹이나 참조 혹은 Breaking Changes 등을 추가할 수 있습니다.
  
  • 이슈 트래킹 (Issue Tracking): 이슈 트래킹을 위해 푸터에 해당 이슈 번호를 추가할 수 있습니다. 여러가지 키워드가 있으며 대표적으로 Fixes, Closes, Resolves 키워드가 존재합니다.
    • 기본 문법:  <키워드>: <이슈 번호>
      • Fixes: #<issue-number>: 특정 이슈를 수정하거나 해결했음을 나타냄 (버그 수정의 뉘앙스)
      • Closes: #<issue-number>: 특정 이슈를 닫음을 나타냄
      • Resolves: #<issue-number>: 특정 이슈를 해결했음을 나타냄 (기능 완성의 뉘앙스)
  • Reference: 참조를 위한 이슈 번호나 외부 링크 혹은 문서를 추가할 수 있습니다. 공식적인 키워드 혹은 정해진 문법은 없으나 See, See also 와 같은 구문을 자주 사용합니다.
  • Breaking Changes: 커밋이 호환성에 영향을 주는 변경 (Breaking Change) 을 포함할 때, 이를 푸터에 명시할 수 있습니다.
    • 기본 문법: BREAKING CHANGE: <description>

Conventional Commits 메시지 작성 규칙 및 예시

엄격히 강제된 규칙은 없으나 일반적으로 아래와 같은 경향이 있습니다.

• type:
  • 소문자로 작성
• scope:
  • 소문자로 작성
• description:
  • 소문자로 시작하며 한 줄로 간결하게 작성
  • 제목처럼 간결한 요약이므로 불필요한 마침표는 생략
• body:
  • 대문자로 시작하며 문장 형식으로 작성
  • 여러 문장이 나올 경우 다음 줄에 작성
• footer:
  • 대문자로 시작하며 종류별로 나열
  • 줄을 비우지 않고 연달아 작성
  • 보통 이슈 트래킹 관련, 참조 관련, Breaking Changes 순으로 작성
  • Breaking Changes 는 여러 문장일 경우 내용이 길어지면 줄바꿈을 권장하며 길지 않다면 줄을 바꾸지 않아도 무방

fix(api): resolve data formatting issue in user endpoint

- The user endpoint was returning incorrectly formatted data
- This change fixes the issue by updating the response serializer
- Additional tests have been added to ensure proper functionality

Fixes #101
Fixes #102
See: https://example.com/docs/api-updates
See #103
BREAKING CHANGE: Removed support for legacy API endpoints. Use the new /v2 endpoints instead.

시제 관련

Conventional Commits 에서 선호되는 시제는 명령형 (imperative) 입니다. 즉, 커밋 메시지를 “이 변경이 무엇을 한다” 로 해석되도록 작성하는 것이 핵심입니다. 다만, 이는 header 부분에 해당하는 내용이며 그 외 body 나 footer 에서는 다른 시제를 사용해도 무방합니다. Conventional Commits 를 따르는 다음과 같은 경우의 시제 사용 권장은 다음과 같습니다.

항목	Conventional Commits 관련 요소	시제 권장
PR 요청 제목	header	명령형 권장
PR 수락 시 Commit message	header	명령형 권장
PR 수락 시 Extended description	body	명령형일 필요 없음
PR 요청 본문	관련 없음	관련 없음