69. 커밋 메시지 컨벤션 (Commit Message Convention)

⚠️ 이 문서는 여러 명의 개발자가 협업하는 깃(Git) 환경에서, 아무렇게나 휘갈겨 쓴 커밋 메시지(수정함, 진짜최종)가 초래하는 의사소통 비용과 재앙을 막기 위해, feat, fix, docs 등의 규격화된 접두어(Prefix)를 사용하여 소스 코드의 변경 의도를 명확히 하고 릴리스 노트 작성까지 자동화하는 '커밋 메시지 표준화(Convention)' 규칙을 다룹니다.

핵심 인사이트 (3줄 요약)

  1. 본질: "내가 이 소스 코드를 왜 바꿨는지"에 대한 요약문을 인간 동료와 기계(CI/CD 봇)가 모두 오해 없이 명확하게 읽을 수 있도록 약속된 템플릿(문법)을 강제하는 협업 문화다.
  2. 가치: 버그가 터졌을 때 수만 줄의 깃 족보(History)를 뒤지며 원인을 찾을 때, 규칙적으로 정리된 커밋 메시지는 검색 속도를 비약적으로 높여준다. "누가 이 따위로 고쳤어!"라는 감정적 싸움을 막는 훌륭한 백서(History Book)가 된다.
  3. 기술 체계: 구글이나 앵귤러(Angular) 팀의 컨벤션이 사실상 업계 표준으로 쓰이며, 타입(Type), 본문(Body), **꼬리말(Footer: 이슈 트래커 번호 연결)**의 3단 구조로 작성하는 것이 정석이다.

Ⅰ. 아무렇게나 쓴 커밋 메시지의 재앙

코드만 잘 짜면 끝나는 것이 아니다. 코드는 3개월 뒤의 나도 못 알아본다.

  1. 최악의 커밋 이력들:
    • Update login.js (뭘 업데이트했다는 건가?)
    • 버그 수정 (어떤 버그를 어떻게 고쳤다는 건가?)
    • asdfasdf (퇴근 직전의 분노가 담긴 무의미한 타이핑)
  2. 소통 비용(Communication Cost)의 폭발:
    • 이런 메시지가 쌓인 저장소에서 치명적 결제 에러가 터졌다고 치자.
    • 동료들은 범인(문제가 된 코드 라인)을 찾기 위해 이 수백 개의 쓸모없는 커밋들을 1번부터 끝까지 일일이 다 까서 소스코드를 눈으로 대조해야 하는 지옥을 겪는다.
  3. 가독성의 위기:
    • 코드를 수정하는 행위는 '기능 추가', '버그 수정', '오타 수정' 등 다양한 목적이 섞여 있다. 이 목적을 분류하지 않으면 프로젝트의 진행 방향(어느 기능이 개발 중인지)을 관리자(PM)가 파악할 수 없다.

📢 섹션 요약 비유: 서류철에 문서를 철할 때 겉표지에 '서류1', '수정본', '진짜최종'이라고만 적어놓으면 나중에 1년 전 계약서를 찾을 때 캐비닛을 다 뒤집어 엎어야 합니다. 커밋 컨벤션은 서류 겉면에 [23년 계약서-영업부-홍길동-삼성전자 건]이라고 규격화된 라벨 스티커를 꼼꼼하게 붙이게 강제하는 서류 정리의 절대 규칙입니다.

Ⅱ. 업계 표준: 앵귤러(Angular) 커밋 컨벤션 3단 구조

전 세계 개발자들이 가장 사랑하는 일종의 '커밋 문법'이다.

  1. 제목 (Header): [타입] + [짧은 요약]:
    • 50자를 넘지 않는 명확한 한 줄 요약이다. 가장 중요한 **접두어(Type)**로 시작한다.
    • feat : 새로운 기능 추가 (예: feat: 카카오 소셜 로그인 기능 추가)
    • fix : 버그 수정 (예: fix: 결제 시 포인트 차감 안 되는 오류 수정)
    • docs : 문서 수정 (README.md 등)
    • style : 코드 포맷팅, 세미콜론 누락 수정 (비즈니스 로직 변경 없음)
    • refactor : 코드 리팩토링 (버그 수정이나 기능 추가 없는 구조 개선)
    • test : 테스트 코드 추가 및 수정
    • chore : 빌드 업무 수정, 패키지 매니저(npm) 설정 등 기타 잡무
  2. 본문 (Body): 왜(Why)와 어떻게(How):
    • 제목 밑에 한 줄을 띄우고 상세한 설명을 적는다. "어떤 코드를 바꿨는지"는 Git이 Diff로 보여주니 적을 필요 없고, **"왜 이 코드를 이 방식으로 바꿨는지(의도)"**를 친절하게 설명해야 동료가 리뷰(PR)하기 편하다.
  3. 꼬리말 (Footer): 이슈 트래커 연동:
    • 맨 아랫줄에는 Resolves: #123 (이슈 123번 해결) 또는 Related to: #45 처럼 JIRA나 GitHub Issue 번호를 적어준다.
    • 이렇게 적어두면 나중에 지라(JIRA) 티켓을 열었을 때 이 커밋 코드가 자동으로 링크되어 기획자와 개발자의 완벽한 업무 추적(Traceability)이 완성된다.

📢 섹션 요약 비유: 뉴스 기사를 쓸 때 쓰는 완벽한 피라미드 구조입니다. 제목(feat)만 보고도 "아, 새 기능이구나!" 하고 직관적으로 알 수 있고, 관심이 생기면 본문을 읽어 "아, 보안 이슈 때문에 이렇게 개발했구나" 하고 이유를 납득하며, 마지막 꼬리말 번호를 클릭해 "기획팀의 이 요구사항 명세서 때문에 시작된 작업이구나" 하고 전체 맥락을 한 번에 꿰뚫어 보는 기사 작성법입니다.

Ⅲ. CI/CD 로봇의 개입 (Semantic Versioning 자동화)

커밋을 예쁘게 쓰면 놀랍게도 배포(Release) 업무가 통째로 사라진다.

  1. Conventional Commits (기계가 읽는 커밋):
    • 앵귤러 컨벤션을 로봇이 쉽게 파싱할 수 있게 규격화한 약속이다.
    • 개발자들이 feat: ~ 과 fix: ~ 로만 규칙을 지켜서 열심히 main 브랜치에 코드를 모았다고 가정하자.
  2. 릴리스 노트 (Release Note) 1초 자동 생성:
    • 다음 달에 v2.0 버전을 배포할 때, semantic-release 같은 봇(Bot)을 실행한다.
    • 로봇이 지난달부터 쌓인 커밋 메시지를 쫙 스캔하여, feat가 붙은 것들은 [새로운 기능] 칸에 묶어주고, fix가 붙은 것들은 [버그 픽스] 칸에 묶어주어 완벽하고 아름다운 'v2.0 업데이트 내역서'를 1초 만에 자동 생성해 낸다.
  3. 시맨틱 버저닝(SemVer) 자동 업데이트:
    • 로봇은 커밋 제목을 보고 소프트웨어의 버전(v1.0.0) 숫자도 알아서 올린다.
    • fix 커밋만 있으면 v1.0.1 (패치 버전)로 올리고, feat 커밋이 발견되면 v1.1.0 (마이너 버전)으로 올리며, 꼬리말에 BREAKING CHANGE(기존 하위 호환성 깨짐)라는 단어가 감지되면 과감하게 v2.0.0 (메이저 버전)으로 앞자리를 올려버리는 완전 자동화(CD)가 실현된다.

📢 섹션 요약 비유: 직원들(개발자)이 매일 쓰는 업무 일지(커밋 메시지) 양식을 완벽하게 통일시켜 놓으면, 나중에 사장님(관리자)이 연말 결산 보고서(릴리스 노트)를 만들 때 직원들을 괴롭히며 엑셀을 취합할 필요 없이, 로봇 비서가 업무 일지 제목만 쓱 스캔해서 단 1초 만에 완벽한 연말 성과 보고서를 프린트해 주는 마법 같은 사무 자동화의 힘입니다.