프로젝트를 하면서 간간히 커밋 컨벤션을 정의하긴 했었으나, 더 많은 사람들이 알고 있는 컨벤션에 익숙해지는 게 먼저일 것 같아 유명한 컨벤션인 Udacity 컨벤션을 직접 번역해보며 정리하고자 한다.
소개
이 스타일 가이드는 프로젝트 수행 시 준수해야 할 공식 가이드로서 역할합니다. Udacity의 평가자들은 프로젝트를 평가할 때 이 가이드를 참고합니다. 소프트웨어 개발 분야에서는 "이상적인" 스타일에 대한 다양한 견해가 존재합니다. 따라서 프로젝트 진행 중인 학생들에게 혼란을 방지하기 위해 본 가이드를 참조하도록 권고하고 있습니다.
커밋 메시지
메시지 구조
커밋 메시지는 공백 라인으로 구분된 세 가지 명확한 부분으로 이루어져 있습니다: 제목, 선택적으로 본문, 그리고 선택적으로 바닥글입니다. 레이아웃은 아래와 같이 구성됩니다:
type: Subject
body
footer제목은 메시지의 유형과 주제로 이루어져 있습니다.
타입 (The Type)
타입은 제목 안에 포함되어 있으며 다음 중 하나일 수 있습니다:
- feat: 새로운 기능 추가
- fix: 버그 수정
- docs: 문서 변경
- style: 서식, 누락된 세미콜론 등의 변경; 코드 변경 없음
- refactor: 프로덕션 코드 리팩터링
- test: 테스트 추가, 테스트 리팩터링; 프로덕션 코드 변경 없음
- chore: 빌드 작업, 패키지 매니저 구성 등 업데이트; 프로덕션 코드 변경 없음
제목 (The Subject)
제목은 50자를 초과하지 않아야 하며 대문자로 시작하고 마침표로 끝나지 않아야 합니다.
커밋이 무엇을 하는지 설명할 때는 명령조를 사용하세요. 예를 들어, change 대신에 changed나 changes를 사용하지 마세요.
본문 (The Body)
모든 커밋이 본문을 필요로 하는 복잡성을 가지지는 않습니다. 따라서 본문은 선택적이며 커밋에 설명과 맥락이 필요한 경우에만 사용합니다. 본문을 사용하여 커밋의 '무엇'과 '왜'를 설명하고 '어떻게'는 설명하지 않습니다.
본문을 작성할 때는 제목과 본문 사이의 빈 줄이 필요하며 각 줄의 길이를 72자 이하로 제한해야 합니다.
바닥글 (The Footer)
바닥글은 선택적이며 이슈 트래커 ID를 참조할 때 사용합니다.
예시 커밋 메시지
예시 커밋 메시지를 소개하고 있는데, body 부분은 너무 길다. 그냥 이런 구조로 작성하는구나라고 이해하면 될 듯 하다.
// header
feat: Summarize changes in around 50 characters or less
// body
More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In some contexts, the first line is treated as the
subject of the commit and the rest of the text as the body. The
blank line separating the summary from the body is critical (unless
you omit the body entirely); various tools like `log`, `shortlog`
and `rebase` can get confused if you run the two together.
Explain the problem that this commit is solving. Focus on why you
are making this change as opposed to how (the code explains that).
Are there side effects or other unintuitive consequences of this
change? Here's the place to explain them.
Further paragraphs come after blank lines.
- Bullet points are okay, too
- Typically a hyphen or asterisk is used for the bullet, preceded
by a single space, with blank lines in between, but conventions
vary here
If you use an issue tracker, put references to them at the bottom,
like this:
// footer
Resolves: #123
See also: #456, #789실제 작업 시 어떻게 적용할까?
일단 가장 크게 새로 알게 된 점은, 제목과 본문에 글자 수가 제한되어 있다는 점이다. 지금 든 생각으로는 본문은 제목만으로 어떤 작업을 했는지 부족하다고 생각될 경우에만 작성해도 충분할 것 같고, 특히 커밋의 '무엇'과 '왜'만 담아낼 수 있도록 노력해야겠다고 생각이 들었다. 제목의 내용, 본문의 내용을 구체적으로 어떻게 작성해야 좋은 경우고 어떻게 작성하면 좋지 않은 경우인지는 직접 해 봐야 알 것 같다.
여담: 제목 작성에 관하여
다른 분들이 작성한 커밋 컨벤션 규칙들을 보면, 제목은 동사로 시작하여 명령형으로 작성하라는 식으로 표현된 경우가 많았다. 예시로 아래와 같이 말이다.
Feat: "추가 get data api 함수"
그런데 개인적으로 이는 영어의 표현을 한국어로 번역하는 과정에서 생기는 애매한 오류 같다는 생각이 들었다.
취지는 공감된다. 깃에서 merge 이벤트가 발생했을 시, 아래와 같은 로그가 남게 된다.
Merge branch 'test'
이 경우에도 동사 (merge)가 먼저 오기 때문에 한글로 작성할 때도 동사가 먼저 오는 게 적합하다는 의도인데, 한글로 작성할 것이라면 한글로 읽었을 때 자연스러워야 더 협업에 적합하지 않을까? 라는 생각이 들어 나는 위의 한글 커밋을 다음과 같은 방향으로 작성하려고 한다.
Feat: get data api 함수 추가
물론 컨벤션은 협업 시에 정한 컨벤션을 따르는 게 가장 맞겠지만, 프리코스 등 혼자서 작업할 때 연습을 하기 위한 컨벤션은 위와 같은 방향으로 진행해보려고 한다.
Reference
