2025. 5. 29. 09:09ㆍ카테고리 없음
요즘 프로그래밍 공부를 하면서 ' 하... 이걸 조금만 더 일찍 알았더라면 좋았을텐데..! ' 라는 생각이 드는 순간이 참 많다.
이번에 소개하려하는 commit message convention은 그중 가장 아쉬웠던 개념이라 첫 포스팅 주제로 선정하게 되었다.
혹시나, 나처럼 아직 commit message convention이라는 말을 처음 들어보는 사람이 있다면
지나치지 말고 꼭 한번 읽어보길 추천한다.
혹시 지금 당신의 commit 메시지, 이렇게 생기진 않았나요?
뭐 나보다 심한 사람은 없을거라고 생각한다.. 지난날의 죄악들.. 과거의 나.. 하... 아무것도 모르고...
팀원들도 찐최종 남발하고 난리였네... ( 그래도 우리 열심히 했잖아 ~ 하하.... ) 🤦♂🤦♂
혹시, 그냥 쓰면 되는거 아닌가? 라는 생각을 하고 있다면..
아니다. 쓰는 법이 분명히 있다. 설명에 앞서, 잘 작성된 commit 메시지는 어떻게 생겼는지 보자.
꼭 영어로 쓰지 않아도 된다. 한글로도 좋은 commit 메시지를 남길 수 있다.
함께 협업하는 사람이 어떤 사람이면 좋겠는지 생각해본다면,, 커밋습관을 얼른 고쳐야겠다는 생각이 들 것이다.
👨💻 Commit Message Convention은 왜 지켜야하고, 어떤 내용이 담겨야할까?
예전에도, 지금도, 그리고 앞으로도 사회적으로 요구되는 가장 중요한 능력은 커뮤니케이션일 것이다.
개발자들은 특히 협업을 통해 작업하는 경우가 많기에 더욱더 이 커뮤니케이션 능력이 중요하다.
흔히 성격좋고, 말 잘 통하는걸 커뮤티케이션 능력이라고 생각할 수 있지만, 개발자라면 짧고 명확하게 전달할 줄 알아야 한다. 그리고 그게 ‘대화’의 형태로만 요구되는 것이 아니다.
'클린한 코드' 그리고 ‘커밋메시지’
내가 어떤 기능을 작성했는지, 그리고 기존 코드를 수정했다면 '왜', '무엇을', '어떻게' 수정했는지.
커밋메시지를 통해서 정확한 이유과 의도가 전달될 수 있어야한다.
본인이 개발한 코드 아닌 경우, 코드를 파악하기 위해서 불필요한 시간과 에너지가 낭비될 수도 있기 때문이고,
구현 전, 팀원간 기능 설계에 대한 논의가 충분히 이뤄졌더라도, 구조에 대한 이해가 완료된 상황이라도,
직접 구현한 파트가 아니라면 어떤 기능을 구현해서 push한 것인지 한눈에 알아보기가 어렵기 때문이다.
또한 커밋 메시지가 명확해지면 진행상황도 파악하기 쉬워지게 된다.
내가 팀리더나 PM이라면?
입장을 바꿔 내가 팀 리더나 프로젝트 매니저라고 생각해본다면,
왜 커밋 메시지를 지켜야하는지, 그리고 그것이 왜 기본적인 예의인지 와닿지 않을까 싶다.
commit message convention일 지키는 것은 소통이자, 서로 피로도를 줄이는 기본적인 예의이다.
👨💻 그렇다면, 어떻게 작성해야할까?
커밋 메시지 규약은 제목(subject)-본문(Body) - 꼬리문(footer) 형태로 이루어져있다.
하지만 그 중, 우리에게 중요한건 subject이다.
나머지 body와 footer는 선택사항으로 각각 추가설명, 이슈참조 정도의 역할을 하고 있기 때문이다.
▶️ subject
subject는 아래와 같이 작성하면 된다.
<타입>(범위): 커밋 메시지
예시) feat(view): 상품 상세 페이지에 리뷰 기능 추가
fix(cart): 장바구니 수량 오류 수정
refactor(order): 주문 로직 함수 분리 및 리팩토링
이때, 타입은 커밋한 작업의 목적과 의도에 맞게 작성을 해주면 되고,
타입의 종류
- feat: 새로운 기능 추가
- fix: 버그 수정
- refactor: 기능의 변경없이 코드를 개선하는 리팩토링
- docs: 문서 변경
- test: 테스트 코드
- build: 빌드 파일 수정
- style: 코드 스타일, 포맷, 정렬, 공백 등을 수정
- CI: 코드 통합시 자동 빌드 및 테스트하는 CI관련 설정 수정
- chore: 설정, 빌드, 기타 잡무
범위는 해당 작업이나 변경사항이 어디서 발생한건지 작성하며 보통 도메인, 레이어, 기능 단위 등을 기재한다.
참고로 범위는 생략가능하다.
커밋 메시지는 '무슨작업을 했는지', '무엇을, 왜 바꿨는지' 명확하고 간결하게 작성해야한다.
예시 ) feat(product): 상품 등록 기능 구현
fix(order): 주문 취소 시 재고가 복원되지 않는 문제 해결
refactor(view): 상품 출력 형식을 테이블 형태로 변경
docs: README에 프로젝트 실행 방법 추가
test(product-service): 상품 가격 계산 로직 단위 테스트 추가
chore: .gitignore에 log 파일 확장자 추가
▶️ body & footer
본문과 꼬리말은 선택사항으로 각각 추가설명, 이슈참조에 해당한다.
본문에는 변경한 이유나 추가설명이 필요한 경우에 '무엇을' , '왜 했는지' 중점적으로 작성하면 된다.
꼬리말은 이슈트래킹이나 Breaking change를 알리기 위한 용도로 사용된다.
현재 커밋내용이 Github 이슈와 관련있다면 아래 키워드를 이용해서 이슈번호를 연결해준다.
- Closes #이슈번호 -> 해당 커밋을 통해 이슈가 해결(close)되는 경우
- Fixes #이슈번호 -> 이슈에 해당하는 버그를 수정한 경우
(Github 이슈가 무엇인지 어떻게 활용하는지에 대한 내용은 잘 다듬어서 다음에 포스팅으로 공유해보겠습니다)
또한 해당 커밋이 기존코드의 호환성을 깨뜨리는 변경사항을 발생시킨다면 footer에 해당 내용을 작성하여 알려야 한다.
대문자로 BREAKING CHANGE 키워드를 써서 어떤 변경사항이 생겼는지 설명하면 된다.
예시 1 ) fix(order): 주문 취소 시 재고가 복원되지 않는 문제 해결
주문 취소 시 해당 상품의 재고가 복원되지 않는 문제 수정
OrderService에서 cancelOrder 메서드 호출 시, 각 주문 상품의 수량만큼 상품의 재고가 증가하도록 로직 추가
또한, 테스트 코드에서도 해당 케이스를 검증하도록 수정
Resolves: #42
예시 2 ) refactor(payment): 결제 처리 함수의 파라미터 구조 변경
유지보수성을 개선하기 위해 결제 처리 함수의 파라미터를 단순화하고, 결제 정보 객체 하나로 통합했습니다.
기존에 개별 파라미터로 값을 전달하던 코드 전반에 영향이 있습니다.
BREAKING CHANGE: processPayment 함수의 파라미터 형식이 변경되어 기존 방식으로 호출 시 오류가 발생할
수 있습니다.
사실, 형식보다 더 중요한건 커밋을 하는 시점이다.
앞서 commit message를 작성하는 규칙에 대해서 알아봤으나, 사실 그보다 더 중요한 것은 '언제 커밋해야하는지', 그 시점이다.
이전에 나는 하루작업을 끝내고 커밋을 하거나, 하나의 파일을 완성해서 파일을 저장할때 커밋을 했었다. 심지어 프로젝트 중에는 그 다음날 이어서 계속 작업하는 경우가 많았기 때문에 push 내역도, 작업내용을 담은 commit메시지도 없는 날들이 많았다.
나는 Github를 그저 클라우드 드라이브마냥 '저장'하는 용도로만 사용했던 것이다.
커밋은 단순한 저장이 아니라, 작업기록을 남기고 변경 사항을 기록하는 과정이다.
하나의 기능 단위가 완성됐을 때,
버그를 수정했을 때,
코드를 리팩토링했을 때,
배포에 영향을 주는 설정을 변경했을 때,
매번 커밋을 해주어야한다. 가장 중요한 것은 '기능단위로 커밋하기' 임을 기억하자!
🙌 포스트를 준비하며...
이전에는 커밋의 중요성이 그렇게 크게 와닿지는 않았었는데, 부트캠프에서 프로젝트를 하면서 협업을 해보니 commit message가 참 중요하다는걸 느끼게 되었다. 작성한 코드에 적절하게 주석을 달고 왜 고쳤는지 이유를 남기고...
커밋을 잘 작성하면 함께 협업하는 사람이 보기에도 나의 작업진행상황이 한 눈에 보이고, 내 코드에 대한 불필요한 질문을 덜 할 수 있게 만들어준다. 시간낭비가 줄고, 팀생산성이 올라간다.
좋은 커뮤니케이션이 서로간 작업의 피로도를 줄여준다는것을 느끼게 되어
개발 커뮤티케이션의 기초인, 커밋에 대한 내용으로 포스팅을 하게되었다.
커밋 메시지를 잘 쓴다는 건,
코드를 잘 짠다는 것만큼이나 협업에서 중요한 역량입니다.