@vendys/commitlint-config

Commit Message Style Guide

이 가이드는 벤디스에서 VCS (Version Control System)를 사용하며 변경이력을 작성할 때 기준이 되는 스타일을 설명한다.

코드를 비교하는 diff는 변경된 코드가 무엇인지만 보여줄 뿐 변경이 일어난 배경(context)을 설명하는 것은 커밋 메시지(commit message)다. 그리고 커밋 메시지를 더 쉽게 읽을 수 있도록 작성할 때, 이를 통해 더 나은 정보를 제공할 수 있다.

노트: 이 가이드는 commitlint를 사용한다고 가정한다.

Table of Contents

1. 원자적 커밋(Atomic Commit)
2. 커밋 메시지 형식
3. Header
4. Body
5. Footer
6. 도움이 되는 글

원자적 커밋(Atomic Commit)

"원자적(atomic)" 커밋은 잘못 커밋한 코드를 쉽게 복원(revert)할 수 있는 단위로 커밋하는 것을 의미하며, 하나의 버그 수정 또는 하나의 기능 추가를 중심으로 한 변경이 그 단위가 된다. 따라서 하나의 기능에 대해 여러 번의 수정이 있을 때도 기능을 쉽게 제거할 수 있게 한 번만 커밋하는 것이 좋다. 또, 원자적 커밋은 다른 변경 사항의 반영이나 다른 브랜치와의 통합(merge)를 쉽게 할 수 있도록 돕는다.

• 각 버그 수정 또는 작업을 독립된 변화로 커밋
• 업무의 한 덩어리가 완료될 때 커밋
• UI 레이아웃의 변경은 각각 분리해 커밋
• 레이아웃 파일, 관련된 코드, 추가된 리소스를 함께 커밋

⬆ 맨 위로

커밋 메시지 형식

• 2.1 커밋 메시지는 크게 header, body, footer로 구성된다.

  {header}
  
  {body}
  
  {footer}

• 2.2 커밋 메시지에 header는 반드시 존재해야 하며, body, footer는 생략 가능하다. commitlint: header-min-length, body-min-length, footer-min-length

  <!-- 잘못된 예 -->
  
  {body}
  
  {footer}
  
  <!-- 올바른 예 -->
  
  {header}
  
  {body}
  
  {footer}

• 2.3 body 앞에 빈 줄을 사용한다. commitlint: body-leading-blank

  <!-- 잘못된 예 -->
  
  {header}
  {body}
  
  <!-- 올바른 예 -->
  
  {header}
  ↵
  {body}

• 2.4 footer 앞에 빈 줄을 사용한다. commitlint: footer-leading-blank

  <!-- 잘못된 예 -->
  
  {header}
  ↵
  {body}
  {footer}
  
  <!-- 올바른 예 -->
  
  {header}
  ↵
  {body}
  ↵
  {footer}

• 2.5 커밋 메시지의 한 줄이 한글 36자를 넘으면 줄 바꿈을 한다.

  <!-- 잘못된 예 -->
  
  일이삼사오육칠팔구십일이삼사오육칠팔구십일이삼사오육칠팔구십일이삼사오육칠팔구십일이삼사오육칠팔구십일이삼사오육칠팔구십일이삼사오육칠팔구십
  
  <!-- 올바른 예 -->
  
  일이삼사오육칠팔구십일이삼사오육칠팔구십일이삼사오육칠팔구십일이삼사오육
  칠팔구십일이삼사오육칠팔구십일이삼사오육칠팔구십일이삼사오육칠팔구십

⬆ 맨 위로

Header

• 3.1 header는 type, scope, subject로 구성된다.

  {type}({scope}): {subject}
  
  {body}
  
  {footer}

• 3.2 type은 반드시 존재해야 한다. commitlint: type-empty, type-min-length

  <!-- 잘못된 예 -->
  
  ({scope}): {subject}
  
  <!-- 올바른 예 -->
  
  {type}({scope}): {subject}

• 3.3 type은 커밋되는 변경 내용에 따라 다음 중 하나로 명시한다. commitlint: type-enum

  • revert: 기존 커밋으로 복구하는 경우
  • build: 빌드 시스템 또는 외부 의존성과 연관된 변화
  • ci: CI 설정 파일 또는 스크립트와 관련된 변화
  • docs: 문서의 변경만 포함
  • feat: 한 가지 새로운 기능
  • fix: 한 가지 버그 수정
  • perf: 성능을 개선하기 위한 코드 변경
  • refactor: 버그의 수정 또는 기능의 추가가 아닌 코드 수정
  • style: 코드의 의미에 영향을 끼치지 않는 변경
  • test: 누락된 테스트 추가 또는 기존 테스트의 수정

  <!-- 잘못된 예 -->
  
  chore({scope}): {subject}
  
  <!-- 올바른 예 -->
  
  build({scope}): {subject}

• 3.4 type은 반드시 소문자로 작성한다. commitlint: type-case

  <!-- 잘못된 예 -->
  
  DOCS({scope}): {subject}
  
  <!-- 올바른 예 -->
  
  docs({scope}): {subject}

• 3.5 scope은 관련된 이슈 식별자로 지정하며, 특정하기 어려운 경우 생략할 수 있다. commitlint: scope-empty, scope-min-length

  <!-- GitHub 이슈의 예 -->
  
  build(#1): {subject}
  
  <!-- Jira 이슈의 예 -->
  
  build(ISSUE-1): {subject}

• 3.6 scope은 반드시 대문자로 작성한다. commitlint: scope-case

  <!-- 잘못된 예 -->
  
  docs(issue-1): {subject}
  
  <!-- 올바른 예 -->
  
  docs(ISSUE-1): {subject}

• 3.7 subject는 반드시 존재해야 하며, 변경 내용에 대한 간결한 설명을 포함한다. commitlint: subject-empty, subject-min-length

  <!-- 잘못된 예 -->
  
  docs(ISSUE-1)
  
  <!-- 올바른 예 -->
  
  docs(ISSUE-1): {subject}

• 3.8 subject는 현재형, 개조식으로 작성하며, 마지막에 마침표를 찍지 않는다. commitlint: subject-full-stop
type이 revert인 경우 subject에는 복원되는 커밋의 SHA 해쉬를 명시한다.

  <!-- 잘못된 예 -->
  
  docs(ISSUE-1): 변경 내용을 반영한다.
  
  <!-- 올바른 예 -->
  
  docs(ISSUE-1): 변경 내용을 반영

⬆ 맨 위로

Body

• 4.1 body는 변경이 일어난 이유와 기존 동작과의 차이 등을 설명하며, 현재형, 명령형으로 작성한다.

  <!-- 잘못된 예 -->
  
  docs(ISSUE-1): 변경 내용을 반영
  
  문서를 변경했다.
  
  <!-- 올바른 예 -->
  
  docs(ISSUE-1): 변경 내용을 반영
  
  문서의 가독성을 높이기 위해 제목의 스타일을 변경한다.

⬆ 맨 위로

Footer

• 5.1 footer는 커밋을 통해 종료(close)되는 이슈를 참조한다.

  docs(ISSUE-1): 변경 내용을 반영
  
  문서의 가독성을 높이기 위해 제목의 스타일을 변경한다.
  
  ISSUE-1 #resolve

• 5.2 하위 호환성을 깨트리는 커밋은 footer에 관련된 정보를 기술해야 하며, 깨진 호환성에 대한 정보는 BREAKING CHANGE:와 하나의 스페이스 또는 두 개의 줄 바꿈으로 시작한다.

  docs(ISSUE-1): 변경 내용을 반영
  
  문서의 가독성을 높이기 위해 제목의 스타일을 변경한다.
  
  BREAKING CHANGE: 기존과 목차가 달라지고, 섹션으로 가기 위한 링크가 변경된다.
  
  ISSUE-1 #resolve

⬆ 맨 위로

도움이 되는 글

• How to Write a Git Commit Message -- Chris Beams
• On commit messages -- Peter Hutterer (번역)
• Developer Tip: Keep Your Commits “Atomic” -- Sean Patterson
• Writing Good Commit Messages -- D.J. Marcolesco (번역)
• Angular Commit Message Guidelines
• AngularJS Git Commit Message Conventions (번역)
• Conventional Commits

⬆ 맨 위로