Commit Message Conventions

들어가기전

본 문서는 지극히 주관적이며 현업에서 개발자 작업 효율성을 높이기 위해 커밋 메시지 컨벤션을 정립한다.

브랜치는 크게 ASP, Solution 구분하여 관리한다. 세부적으론 파생되는 브랜치들이 많은데, 기존 커밋 메시지 컨벤션은 제약 사항이 많고 불편했다.

앞으로 제시할 새로운 커밋 메시지 컨벤션을 통해, 효율적으로 소스 코드를 관리할 수 있길 바란다.

기본적으로 AngularJS Commit Message Conventions을 따른다.

1. 기존 커밋 메세지 형식 문제점

기존 커밋 메시지 컨벤션은 레드마인 일감 번호와 작업한 내용을 작성한다.

<type> <redmine-rev-number> <subject>

<body>

기존 커밋 컨벤션을 규칙을 따라 실무에선 다음과 같이 작성했다.

ref #159862 트리 2뎁스에서도 사용자 개수 노출 조건 처리
ref #162763 사용자 정보 가져오는 부분 수정
ref #145618 웹 로그인 시 패스워드 초기화
ref #161118 OTP 연동 리팩토링
ref #143300, #143337. feat: Simple View 개선 적용

기존 커밋 메시지 컨벤션은 심플하다.

얼핏보면 별 다른 문제가 없어 보인다. 또한, 일감 번호를 함께 볼 수 있다는 장점이 있다.

하지만 기존 커밋 메시지 컨벤션엔 문제가 많다.

커밋 단위에서 기능 추가인지, 수정인지 구분할 수 없다.
- 제일 중요한 치명적인 버그나 보안 이슈에 따른 수정인지 구분할 수 없다.
- 만약 기능 결함으로 인한 수정 사항이라면, 본 브랜치에서 파생된 브랜치들도 적용해줘야 되기 때문이다.
어느 버전에서 발생한 문제인지, 현재 브랜치에서 해결된 문제인지 직관적이지 않다.
- 솔루션 브랜치를 관리하다보면 프로젝트 버전이 매우 중요하다.
- 담당 개발자는 커밋 메시지에 포함된 일감 번호와 기존 소스 히스토리를 분석하여 수정 범위와 적용 브랜치를 판별해야 한다.
기능 파악에 대한 어려움
- 어떤 버전에서 추가된 기능인지 파악이 어려워, 소스 코드 마이그레이션 작업 또는 release 브랜치에 merged 작업 과정에서 어떤 커밋을 포함하고 제외할지 파악하기 어려움이 따른다.
- 개발 능률이 떨어진다.
- 실제 개발하는 시간보다 분석하는 시간이 더 많다.

시간이 지날 수록 히스토리는 파악하기 어렵고, 레드 마인 일감과 소스 히스토리로 분석하는데 상당한 시간을 할애한다.

2. Commit message formatting

위와 같은 일련의 문제점들은 커밋 메시지 형식을 바꾸면 해결할 수 있다.

개선한 커밋 메시지 형식은 다음과 같다.

<type>(<scope>): <subject>

<body>

<footer>

type: 작업 유형
scope: 작업 범위
subject: 작업 제목
body: 작업 상세 내용
footer: 레드마인 일감 번호 또는 연관된 Commit revision number

type

<type> 영역엔 작업 유형을 작성하자.

type	설명
feat	기능 추가
refactor	리펙토링 및 기능 개선
test	테스트 코드 추가
fix	버그 수정
docs	문서 추가
chore	버전 관련
style	코드 수정이 아닌 작업 1. 코드 컨벤션 2. 상위 클래스 복사 작업

커밋 메시지 앞단에 작업 유형을 표시함으로써, 개발자는 기능이 추가됐는지, 수정됐는지 기능 파악에 용이하다.

feat(sol-3.0.0): 대시보드 기능 추가
refactor(2.1.0): JMS 모듈 JPA 튜닝
fix(apple): 원격지 PC 트리 무한 로딩 버그 수정 

유형에 대한 자세한 내용은 AngularJS Commit Message Conventions 참고해라.

scope

<scope> 영역엔 작업 범위를 작성한다.

내부적으로 프로젝트 버전을 기준으로 브랜치를 생성한다. 암묵적 규칙이다. 따라서 <scope>엔 브랜치 명을 명시하자.

다음 3 가지 규칙을 통해 작성하자.

ASP일 경우엔 버전을 명시한다.
솔루션 표준본일 경우엔 sol-[버전]으로 명시한다.
솔루션 납품 브랜치는 브랜치명을 그대로 명시한다.

`<scope>`	branch	branch 설명
2.1.0	origin/release/2.1.0	ASP release 브랜치
2.0.1.3.1	origin/release/2.0.1.3.1	ASP release 브랜치
2.0.1.3	origin/release/2.0.1.3	ASP release 브랜치
sol-2.0.0.1.4	origin/solution/2.0.0.1.4	솔루션 release 브랜치
sol-2.0.0.1.3	origin/solution/2.0.0.1.3	솔루션 release 브랜치
sol-1.0.0	origin/solution/1.0.0	솔루션 release 브랜치
google	origin/solution/google	솔루션 납품 브랜치
apple	origin/solution/apple	솔루션 납품 브랜치
nh	origin/solution/nh	솔루션 납품 브랜치

solution release 브랜치 중에서 상위 브랜치는 당시 버전을 명시한다.
예를 들어 origin/solution/2.0.0.x에서 작업을 해야 한다면, 프로젝트 버전(2.0.0.1.4)을 따라서 작성하면 된다.
ex) feat(sol-2.0.0.1.4) 테스트 코드 추가

버전이 명시되면 개발자가 어느 버전에서 기능 추가가 됐는지 커밋 메시지만 봐도 확인할 수 있다.

소스 관리 시스템에서 특정 버전을 검색하여 추가된 기능들을 확인할 수 있고, 다른 브랜치에 커밋 단위로 구분하여 추가할 수 있다. 소스 마이그레이션에 용이하다.

// ASP 버전
feat(2.0.1): 보안 옵션 기능 추가 

// 솔루션 표준본 버전
feat(sol-2.0.1): 보안 옵션 기능 추가
feat(sol-2.0.0.1.4): 워터마크 기능 추가
feat(sol-1.0.0): 대결자 기능 추가

// 솔루션 납품 버전
feat(apple): 보안 옵션 기능 추가
feat(google): 보안 옵션 기능 추가

한눈에 적용 범위를 파악할 수 있다.
- 예를 들어 특정 릴리즈 브랜치에서 기능 결함 또는 보안 이슈 작업이 파악 가능하다.
ASP, Solution 브랜치 관리 용이
- 하위 브랜치 버전에서 작업이 됐다면, ASP release 브랜치에 포함할지 빠르게 판단할 수 있다.

이외에도 치명적인 기능 결함 또는 버그로 수정된 기능을 적용할 브랜치 범위를 빠르게 파악할 수 있다.

fix(sol-2.0.0.1.4): 사용자 정보 XSS 이슈

- 보안 이슈: XSS 스크립트 공격 가능

예를 들어 솔루션 표준본에서 수정된 버그 수정에 대한 커밋 메시지를 개발자가 빠르게 파악할 수 있고, 해당 브랜치로부터 파생된 모든 납품 브랜치에 커밋 단위로 빠르게 적용할 수 있다.

subject

<subject> 영역엔 커밋 메시지 제목을 작성한다.

커밋 메시지 제목은 간결하고 명확하게 짓는다.

제목은 핵심만 적는다. 간결할 수록 좋다.
개발 히스토리를 담지 않는다.
오히려 너무 간결하면 기능 파악이 어렵다.
제목에 특정 버전을 명시하지 않는다.

## Bad
[1] fix(sol-2.0.0.1.4): 내 정보 수정 화면 html 코드 저장되어 XSS 보안 취약점 조치
[2] refactor(2.1.0): [서비스] 관리자가 등록한 계정으로 초기 로그인 비밀번호 아무거나 입력해도 비밀번호 수정창이 뜸 - 로그인 프로세스 정리 및 리팩토링.  - 2 factor 인증 사용시 인증확인후, 라이선스 체크, 패스워드 알람등 체크로직 추가
[3] refactor(2.1.0): h2 태그 추가
[4] style(2.1.0): 2.1.0 언어 리소스 추가

## Best
[1] fix(sol-2.0.0.1.4): 내 정보 수정 화면 XSS 보안 취약점 조치
[2] refactor(2.1.0): 웹 로그인 인증 프로세스 정리 및 리팩토링
[3] refactor(2.1.0): 원격지 PC 화면 H2 태그 누락으로 인한 추가 
[4] style(2.1.0): 언어 리소스 추가

body

<body> 영역엔 작업에 대한 상세 내용을 작성한다.

코드만으론 작업 히스토리를 완벽히 파악하기 어렵다. 작업 내용을 상세히 적어 개발자에게 도움을 줄 수 있는 내용으로 작성한다.

fix(2.0.1.2.1): ssl redirect 검증 로직 개선

- 신규 한국 서버 구성으로 인한 X-Forwarded-Proto-original 커스텀 헤더 추가

<footer> 영역엔 일감 번호 또는 연관된 Commit revision number를 기입한다.

feat(2.1.0): 계정변경 메뉴 히든 처리, 그룹 이동 제한

- 사용자 계정 그룹 이동 제한 기획으로 인한 수정

ref #160632, 2c31a033

기능 추가

새로운 기능 추가

feat(2.0.1.3): 사용 신청서 추가 대결자 저장 추가

- 기능성 메서드 추가
- 대결자 기능 개선

todo: 신청서 상세 보기 기능 추가
ref #61234

-------------------------------------------------

feat(apple): 시행세칙 보안옵션 기능 추가

- 워터마크 추가
- 어드민 보안옵션 관리 기능 추가

todo: 프론트 시행세칙 관련 View 작업
ref #612345, 2c31a033

테스트 코드

test(2.0.1.3): 대표옵션 컨트롤러 상세보기 테스트 코드 추가

- 허용 IP 테스트 코드 추가

todo: SpyBean 설정 추가

리펙토링

모든 리펙토링 작업

refactor(sol-2.0.0.1.4): Viewer check 로직 불필요한 코드 제거 및 수정

- private -> protected 접근제한자 수정
- 중첩된 depth 메서드 분리 작업
- ViewerCheckService 클래스 구성

todo: 솔루션 커스텀 기능 검토

버그 작업

치명적인 기능 결함
보안 이슈

fix(2.0.1.3.1): TestController @Controller 제거

- XSS 보안 이슈

-------------------------------------------------

fix(sol-2.0.1.1): 원격지 PC 사용자 계정 무한 로딩 이슈 수정

- 상위 부서 로직 NPE 수정

ref #600133

코드 컨벤션 및 상위 소스 복사

코드 로직 수정이 아닌 단순한 코드 컨벤션 작업
상위 프로젝트 코드 복사 작업

style(2.1.0): 사용하지 않는 import 문 제거 및 정리
style(sol-2.0.1.x): 들여쓰기 및 if문 괄호 닫기
style(google): code copy by 1.0.0

버전 작업

표준본 프로젝트 작업
소스 머지 작업
스키마 파일 DML 추가/수정 작업

chore(2.1.0): 2.0.1.3.1 -> 2.1.0 version up

- 도코모 + 2.0.1.3.1 source merged
- pom.xml version 수정

-------------------------------------------------

chore(2.1.0): NextUpdate.sql DML 추가

- 에이전트 테이블 인덱스 추가
- 회사 옵션 테이블 column default 값 변경

문서 관련

문서 파일 추가

docs(2.1.0): 2.1.0 주요 업데이트 사항 문서 추가

- oauth2 로직 추가
- 사용자 인증 추가
- 암호화 키 변경
  - properties jasypt 암호화 키 변경
  - JWT key 변경

-------------------------------------------------

docs(apple): OTP 연동 API 문서 추가

-------------------------------------------------

docs(google): 인사연동 테이블 정의서 문서 추가

- V_USER_INFO 사원 관련 테이블
- V_DEPT_INFO 부서 관련 테이블

4. 마무리

소스 코드 관리 시스템의 관리자는 개발자다.

새로운 커밋 메시지 컨벤션을 따라 커밋을 하더라도 신경을 쓰지 않는다면 의미 없다. 커밋을 단순히 귀찮은 작업 단위라 생각하지 않았으면 한다. 다음 개발자를 위한 배려라 생각했으면 좋겠다.

저자는 협업하고 있는 주변 개발자가 배려 깊은 사람이었으면 한다. 커밋 메시지를 신경써서 작성하자.

Moon

커밋 메시지로 개발 마무리 잘하기