좋은 커밋 메세지를 남겨야 하는 이유
커밋 메시지를 제대로 작성하는 것은 단순히 관습이 아니라 코드의 유지보수성을 높이고 협업을 원활하게 만드는 핵심 요소이다.
프로젝트 규모가 커지면 커질수록 일관성 있는 커밋 메시지는 더 큰 가치를 발휘하게 된다.
커밋 메시지의 7가지 규칙
1. 제목과 본문을 빈 행으로 구분한다.
2. 제목을 50글자 내로 제한한다.
3. 제목 첫 글자는 대문자로 작성한다.
4. 제목 끝에 마침표 넣지 않는다.
5. 제목은 명령문으로 사용하며 과거형을 사용하지 않는다.
6. 본문의 각 행은 72글자 내로 제한한다.
7. 어떻게 보다는 무엇과 왜를 설명한다.타입
- feat: 새로운 기능 추가
- fix: 버그 수정
- docs: 문서 수정
- style: 코드 형식 수정 (포맷팅, 세미콜론 추가 등. 코드의 동작에는 영향을 주지 않음)
- design : 사용자 UI 디자인 변경 등
- refactor: 코드 리팩토링 (기능 변경 없이 코드 구조 개선)
- test: 테스트 코드 추가 또는 수정
- build: 빌드 파일 수정
- ci: CI 설정 파일 수정
- chore: 빌드 과정이나 기타 잡다한 변경 사항
- perf: 성능 개선
- rename: 파일 혹은 폴더명 수정
- remove : 파일 삭제
* 예시)
- 새로운 기능 추가 (feat)
- JWT 기반 인증 시스템을 추가하여, API 접근 시 보안을 강화하는
기능을 도입한 경우.
feat(auth): Add JWT authentication for secure API access- 버그 수정 (fix)
- 사용자 서비스에서 발생한 널 포인터 예외를 해결한 경우.
fix(user): Resolve null pointer exception in user service- 코드 리팩토링 (refactor)
- 기능의 변화 없이 코드 구조를 개선하거나 리팩토링한 경우.
refactor(controller): Restructure user controller logic- 성능 개선 (perf)
- 캐싱 메커니즘을 최적화하여 API 응답 속도를 개선한 경우.
perf(cache): Optimize caching mechanism to reduce API latencyConventional Commits 기본 형식
<type>(<scope>): <subject>
<body> (optional)
<footer> (optional)type : 커밋의 목적을 설명하는 키워드. 예를 들어 기능 추가는 feat, 버그 수정은 fix를 사용.
scope : 변경된 파일 또는 기능의 범위. 선택 사항이지만 구체적인 범위를 명시하면 좋다.
subject : 변경 사항에 대한 간단한 설명. 첫 글자는 대문자로 작성하고 50자 이내로 작성하며 마침표를 붙이지 않습니다.
body : 커밋 제목에서 다 설명할 수 없는 세부적인 내용을 설명.
무엇을 했는지뿐만 아니라 왜 그 작업을 했는지 어떤 문제를 해결했는지 그리고 어떻게 수정했는지를 설명하는 데 유용하다
커밋의 변경 사항이 복잡하거나 팀원들이 변경 사항의 맥락을 이해해야 할 경우 사용한다.
footer : 추가적인 메타 정보를 제공하는 곳. 주로 이슈 번호나 브레이킹 체인지(호환성 깨짐)와 관련된 정보가 여기에 들어간다.
이슈 트래커와 연동할 때 자동으로 이슈를 닫거나, 중요한 변경 사항을 명시할 때 유용하다.
키워드 + 이슈 번호 또는 브레이킹 체인지에 대한 설명을 포함.
ex) Closes #123
- body와 footer를 언제 사용하는가?
body: 커밋이 복잡한 변경 사항을 포함할 때.
팀원이나 향후 유지보수자들이 왜 이 변경이 필요했는지를 알아야 할 때.
커밋이 단순하지 않고 맥락을 설명해야 할 때.
footer: 특정 이슈 번호를 해결하는 커밋일 때.
커밋이 기존 기능에 호환성 문제를 일으킬 수 있을 때 (브레이킹 체인지).
이슈 트래커와 연동하여 자동으로 이슈를 닫거나 연결하고자 할 때.
# 전체커밋 메시지 예시
feat(auth): add JWT authentication for secure API access
Added JWT-based authentication to improve security for API requests.
This replaces the previous session-based authentication system, which
was prone to session hijacking. The new system generates a token on login
that must be included in all API requests.
Closes #42
BREAKING CHANGE: The session-based authentication endpoints have been removed.
1. 제목 (Subject)
feat(auth): Add JWT authentication for secure API accessfeat : 커밋의 타입을 나타낸다.
여기서 feat는 새로운 기능 추가를 의미한다.
(auth) : 커밋의 범위(Scope)를 나타낸다.
이 부분은 어떤 기능이나 모듈에 영향을 주는지를 설명하는 선택적 요소이다.
이 경우 auth는 인증 관련 모듈이나 기능을 의미한다.
add JWT authentication for secure API access : 제목의 주된 내용이다.
JWT 기반 인증을 추가하여 API 접근의 보안을 강화한 것임을 나타낸다.
이 제목은 커밋의 목적을 50자 이내로 간결하게 설명하고 있고 대문자로 시작하고 마침표가 없도록 작성되어있다.
2. 본문 (Body):
Added JWT-based authentication to improve security for API requests.
This replaces the previous session-based authentication system, which
was prone to session hijacking. The new system generates a token on login
that must be included in all API requests.body : 본문에서는 무엇이 변경되었는지와 왜 그 변경이 이루어졌는지를 설명한다.
첫 번째 문장은 JWT 기반 인증을 추가하여 API 요청의 보안을 향상시킨다는 것을 설명한다.
두 번째 문장은 기존의 세션 기반 인증 시스템을 대체했으며 그 이유는 기존 시스템이 세션 하이재킹(세션 탈취) 공격에 취약했기 때문이라는 설명이 이어진다.
마지막 문장은 새로운 시스템이 로그인 시 JWT 토큰을 생성하며 이 토큰이 모든 API 요청에 포함되어야 한다는 기술적인 세부 사항을 설명한다.
왜 이 작업을 했는지와 어떤 문제를 해결했는지를 명확하게 설명함으로써 다른 개발자들이 변경 사항을 쉽게 이해할 수 있다.
3. 푸터 (Footer)
Closes #42
BREAKING CHANGE: The session-based authentication endpoints have been removed.Closes #42 : 이 부분은 이슈 트래커와 연동된 정보를 나타낸다.
이 커밋이 GitHub, Jira와 같은 이슈 관리 시스템에서 42번 이슈를 해결함을 의미하며 해당 커밋이 머지되면 이 이슈가 자동으로 닫히게 된다.
이는 이슈 트래커와 커밋 메시지를 연동해 효율적으로 관리하는 좋은 방식이다.
BREAKING CHANGE : 호환성을 깨는 중요한 변경 사항을 나타낸다.
여기서는 기존의 세션 기반 인증 엔드포인트가 제거되었음을 설명한다.
이 변경으로 인해 기존 API 사용자들은 더 이상 세션 기반 인증을 사용할 수 없으며 JWT 기반으로 전환해야 한다는 것을 의미한다.
이런 중요한 변경 사항은 시스템 사용자들이 미리 알 수 있도록 명시적으로 표시하는 것이 중요하다.
참고 : https://www.freecodecamp.org/korean/news/writing-good-commit-messages-a-practical-guide/
https://blog.munilive.com/posts/my-git-commit-guide.html#google_vignette
