충분한 설명이 있는 커밋 메시지 작성하기

작가님의 허락을 받고 번역한 글입니다.(원문)

소개

이렇게 커밋 하십니까?

이러면 안됩니다! 혼자 개발을 하고, 커밋을 읽을 사람이 없다고 하더라도, 여러분은 결국 3개월 지난 프로젝트를 읽지 못하게 될 겁니다.

"XX 기능을 더했었나?", "내가 햄버거 메뉴 버그를 고쳤었나?"

이렇게 해서는 코드를 확인해보기 전까지는 어떤 것을 더했고, 어떤 버그를 수정했는지 알 수 없습니다. 여러분이 팀과 협업한다고 생각해봅시다. 10개의 커밋을 리뷰해야하는데, 그 커밋 메시지가 충분한 설명을 주지 않는다면, 커밋 10개의 코드를 전부 읽어야 할 것입니다.

1단계: 충분히 묘사된 커밋 메시지

커밋 메시지의 가이드라인에서는 "커밋 메시지는 그것을 읽는 것만으로도 최소한 무슨 작업을 했는지 알수 있어야 한다. "라는 항목이 있습니다. 또한 일반적으로 명령형 문장과 현재 시제를 사용을 요구하고 있습니다.

예를 들면:

• change aspect ratio for company profile video
• add hamburger menu for mobile
• remove unused imports
• fix hamburger menu not opening on mobile
• add test for helper functions
• refactor remove todo logic
• add documentation on hamburger menu
• install react-icons

이렇게 하면 코드 변경 사항을 보지 않더라도 일반적으로 어떤 작업을 했는지 알 수 있습니다.

충분한 설명이 있는 커밋 메시지 작성에 10초 투자함으로써, 미래에 코드 변경 사항을 봐야하는 몇분을 아낄 수 있습니다.

2단계: 그룹화

코드 리뷰나, 오래된 프로젝트를 재활용하고자 할 때, 충분한 설명이 있는 커밋 메시지가 많은 도움이 된다는 것을 배웠습니다.

지금 배운 방법으로는 커밋 메시지를 보며 어떤 작업을 했는지 추측해볼 수 있습니다. 하지만 전체 문장을 읽어야만 기능을 추가한 건지, 삭제한 건지, 버그를 수정한 건지, 패키지를 설치한 건지 알 수 있는 단점이 있습니다. 첫 번째 단어만으로 커밋의 기능을 알 수 있다면 더 좋지 않습니까? 이모티콘을 사용하여 차별화하는 것을 좋아하는 사람들도 있습니다. 원한다면 해도 되지만 저는 하지 않는 것을 권합니다.

이와 관련된 수많은 컨벤션들이 있으며, 저는 주로 Conventional Commit을 활용합니다. 제가 세부 사항(대문자를 써야 하나 말아야 하나, 과거형을 써야 하나, 현재형을 써야 하나, 마침표를 써야 하나 말아야 하나 등)을 추후에 알려드리겠습니다. 그룹화 단계에서는 Conventional Commit을 따릅니다.

아래는 카테고리(아래 예시는 일부분으로 필요에 따라 카테고리를 추가하셔도 됩니다.)입니다.:

• feat, 기능의 추가 혹은 삭제
• fix, 버그 수정
• chore, 패키지 설치 등
• test, 테스트 케이스 추가
• refactor, 기능은 수정하지 않았지만, 코드를 리팩토링 했을 때
• style, 코드의 순서를 바꾸거나, 들여쓰기, 사용하지 않는 패키지 정리 등을 할 때

아래는 위 카테고리를 적용한 예시입니다.:

• feat change aspect ratio for company profile video
• feat add hamburger menu for mobile
• style remove unused imports
• fix hamburger menu not opening on mobile
• test add test for helper functions
• refactor remove todo logic
• docs add documentation on hamburger menu
• chore install react-icons

이런 식으로 커밋을 차별화하면 좀 더 효과적인 설명이 될 수 있습니다. 커밋을 훑어보면서 찾고자 하는 카테고리를 찾을 수 있기 때문입니다.

3단계: Changelog 생성

여러분이 NPM 패키지를 만든다고 해봅시다. 그러면 여러분의 유저들이 변경 사항을 알기 위해서는 Changelog를 만들 필요가 있을 겁니다. changelog를 만들기 위해서 여러분의 git log를 찾아보고, feat과 fix 카테고리에 있는 커밋 메시지를 복사할 수 있습니다. 이 두가지 카테고리는 changelog를 만들 때 가장 많이 쓰입니다. 왜냐하면 유저들은 사용하지 않는 라이브러리나, 세미콜론을 더했는지 등을 알 필요가 없기 때문입니다.

추신: 일반적인 프로젝트를 할 때, 원한다면 더 많은 카테고리를 changelog에 추가할 수 있습니다.

두가지 카테고리의 커밋들을 일일이 선정하는 것은 고되고, 아무도 하고 싶어하지 않는 일입니다. 그렇기 때문에 changelog를 만들기 위해서 standard-version을 사용하면 좋습니다.

단순히 이 명령어를 실행시키면, 자동으로 버전을 만들어내고, changelog, 커밋을 생성하며, 태그가 추가됩니다.

위 이미지는 커밋만으로 생성된 보고서입니다. 우리가 포함을 원하는 카테고리를 지정할 수도 있습니다.

하지만 standard-version과 같은 자동 생성 패키지를 사용하는 것은 단점이 하나 있습니다. standard-verion 프로그램에서 제공하는 규칙을 따라야 한다는 것 입니다.

4단계: Conventional Commits

Conventional Commits는 사람과 기계가 읽을 수 있는 커밋 메시지를 위한 설명서입니다.

여기서 가이드를 읽어봅시다.

이 규칙은 커밋 메시지의 가독성을 향상 시키고 changelog를 자동 생성하는데 도움이 됩니다. 저는 일반적으로 readme 파일에 이 내용을 적어둬서 다른 사람들이 따라할 수 있게 하고 있습니다. 제 요약을 복사해서 여러분 프로젝트에 붙여넣으셔도 좋습니다.

하지만 사이트에 있는 가이드는 꼭 읽어 보시기 바랍니다. 더 상세한 정보가 있습니다.

Commit Message Convention Readme

## Commit Message Convention

이 웹사이트는 [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)을 준수합니다.

커밋 메시지는 [husky and commit lint](https://theodorusclarence.com/library/husky-commitlint-prettier)를 사용해 검증될 예정입니다. 아래 컨벤션을 따르지 않는다면, 커밋하실 수 없습니다.

### 형식

@@@text
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
@@@

* @을 to \`로 바꾸셔야 합니다. dev.to 사이트는 백틱을 여러개 사용하는 것을 허용하지 않고 있습니다.

예시: `feat(pre-event): add speakers section`

### 1. 타입

사용가능한 타입:

- feat → 기능의 추가 혹은 삭제. Ex: feat: add table on landing page, feat: remove table from landing page
- fix → 이슈에 따른 버그 수정 (이슈 없이 진행하지 마십시오). Ex: fix: illustration overflows in mobile view
- chore → 새로운 패키지 설치
- docs → 문서 업데이트
- style → 로직이 아닌 코드의 순서나 공백문자 수정
- refactor → 같은 기능을하지만, 다른 방식으로 수정한 경우
- ci → github workflows, husky를 수정
- test → 테스트 케이스 수정 혹은 추가
- revert → 커밋을 되돌릴 때
- perf → 성능과 관련된 것을 고칠 때

큰 변화의 경우에는 타입 뒤에 느낌표(!)를 더해주시기 바랍니다. Ex: feat!: drop support for internet explorer

### 2. (선택사항) 범위

페이지별 라벨 Ex: feat(pre-event): add date label

\* 범위가 필요하지 않으면 쓸 필요도 없습니다.

### 3. 설명

무엇을 했는지 구체적으로 설명해야합니다.

### 중요 규칙

**여러가지 변경사항이 있다면, 하나씩 커밋해야합니다.**

- 콜론 뒤에는 공백문자 한개가 있어야 합니다. Ex: feat: add something
- `fix` 타입을 사용할 때는 문제 상태를 설명해야합니다. Ex: fix: file size limiter not working
- 명령어와 현재시제를 사용해야합니다.: "changed"이거나 "changes"가 아니라 "change"로
- 문장 앞에 대문자 사용을 금합니다.
- 문장 끝에 마침표 사용을 금합니다.

이 규칙들을 사용하면 changelog는 잘 생성될 겁니다. 그러나 커밋 메시지가 충분히 설명하는지 여부는 여러분에게 달려있습니다.

5단계: Commitlint 추가

팀에 새로운 개발자와 함께 일하고 있다면, 이 컨벤션을 잘 모를 수 있습니다. 이 포스팅을 읽어보라고 하는 동안 😉, 프로젝트를 위한 linter를 추가하시면, 커밋 메시지들이 엉망이 되진 않을 겁니다.

이 프로그램은 여러분이 커밋 메시지를 작성할 때, conventional commit의 사용을 강제할 겁니다.

Husky를 사용하면서 Commitlint를 추가하려면 이 포스팅을 확인해보시기 바랍니다.

요약

충분히 설명하는 커밋 메시지를 사용해야한다. 그렇게 하기 위해서 카테고리를 추가하고, Conventional Commit 규칙을 가이드로 따르자. 그러면 changelog 생성에도 도움이 된다. 그리고 Commitlint를 사용하면 커밋 메시지가 엉망이 되는 것을 막을 수 있다.