commit message 관리 - conventional commit

서비스가 점점 커지면서 관리할 code의 사이즈가 커졌다. Microservice로 구성하다보니 github의 여러 repo를 관리하고 운영하고 있다. service간의 연관성이 있어 새로운 기능을 추가할 때 version 및 changelog를 확인하여 관리하고 있다.

 

Commit message와 version, tag를 수동으로 관리하고 있어 version을 잘못 작성할 때도 많고 tag를 빼먹을 때가 많았다. 문제가 있어 code를 reset하려고 하면 잘못 작성된 version 정보와 tag 때문에 고생할 때가 많았다.

 

Conventional Commits은 커밋 메시지에 명확한 commit 히스토리를 생성하기 위한 간단한 규칙을 제공한다. 이 규칙은 Sementic versioning을 따르며, 이렇게 만들어진 commit 히스토리를 이용하여 쉽게 자동화된 도구를 만들 수 있다.

Sementic version

Sementic version은 X.Y.Z 형태로 한다. X(Major), Y(Minor), Z(Patch)는 각각 자연수로 독립적으로 증가한다.

• Patch: 간단한 버그 수정이 있을 경우, 이전 버전과 호환되는 경우에 증가시킨다.
• Minor: 새로운 기능을 추가했을 경우, 이전버전과 호환되지만 새로운 기능은 이전버전에서 사용할 수 없는 경우 증가시킨다.
• Major: 전면적인 업그레이드여서 이전 버전과는 거의 호환되지 않는 경우 증가시킨다.

semantic version에 대한 자세한 내용은 아래 링크에서 확인가능하다.
유의적 버전 2.0.0 | Semantic Versioning

사용하는 npm package

• husky: git hook 을 트리거하는 용도로 사용한다.
• commitlint: commit 에 대한 linting한다.
• standard-version: 자동으로 npm package.json version을 commit message에 따라 자동으로 update하기 위해 사용한다.

사용방법

husky가 githook 을 덮어쓰기 때문에 husky 설정 이전에 repo를 먼저 초기화 해야한다. 먼저 yarn init git-flow cli를 사용하고 있다면 git-flow init을 먼저 실행하고 아래 명령어를 실행한다.

yarn add husky @commitlint/cli @commitlint/config-conventional standard-version -D

# package.json
{
  ......
  "scripts": {
    "release": "standard-version"
  },
  "husky": {
    "hooks": {
      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
    }
  },
  "commitlint": {
    "extends": [
      "@commitlint/config-conventional"
    ]
  }
}

Message 작성 법

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

• fix: Semantic Version의 PATCH에 대응하는 Message Type이다.
• feat: Semantic Version의 MINOR에 대응하는 Message Type이다.
• BREAKING CHANGE: optional Body나 optional footer를 BREAKING CHANGE: 라는 text로 시작하면 이것은 기존 API와의 호환성을 지키지 않게 됨을 의미한다. Semantic Version의 MAJOR에 대응하고 어느 Message Type에도 적용할 수 있습니다.
• fix와 feat이 아닌 다른 type들을 추가해 사용할 수 있고 보편적으로 build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test를 사용할 수 있다.

# BREAKING CHANGE는 type에 넣으면 error 발생
# BREAKING CHANGE 예시
git commit -m "fix: some message

BREAKING CHANGE: It will be significant"

# docs type 예시
git commit -m "docs: api 문서 변경"

standard version 사용

commitlint와 husky로 commit message를 명확한 커밋 히스토리를 생성할 수 있도록 만들고 standard version으로 version와 changelog를 자동으로 생성하도록 만든다.

standard version은 1.0.0 버전 미만의 version을 사용하는 경우와 1.0.0 이상의 version을 사용하는 경우 다르게 version이 변경된다.

 

• 0.x.x 버전
  배포되기 전 version으로 patch 버전만 변경된다. Message type에 fix, feat, BREAKING CHANGE를 포함하더라도 patch 버전만 증가한다. minor, major version을 증가시키기 위해서는 —release-as option을 사용해야한다.

standard-version --release-as minor
standard-version --release-as 1.1.0

 

• 1.0.0 이상의 버전
  Message type에 따라 version이 변경된다. feat type은 minor version을 fix는 match 버전을 변경한다.

.versionrc file을 사용하여 changelog message를 customize할 수 있다..versionrc의 기본적인 구성은 아래와 같다.

 

> conventional-changelog-config-spec/README.md at master · conventional-changelog/conventional-changelog-config-spec · GitHub

{
  "types": [
    {"type": "feat", "section": "Features"},
    {"type": "fix", "section": "Bug Fixes"},
    {"type": "chore", "hidden": true},
    {"type": "docs", "hidden": true},
    {"type": "style", "hidden": true},
    {"type": "refactor", "hidden": true},
    {"type": "perf", "hidden": true},
    {"type": "test", "hidden": true}
  ]
}

commit 하고 standard-version 명령을 실행하면 version이 update된다. version은 package.json 파일의 version property를 기준으로 변경되며 version 변경 시 자동으로 git tag가 생성된다.

 

git tag에 같은 version의 tag가 존재하는 경우 error가 발생한다. package.json의 version을 수동으로 변경하는 경우 git tag의 version을 확인해야 한다.

# CHANGELOG.md 파일 생성
npm run release --first-commit

# commit message로 CHANGELOG 작성되고 위의 Message Type에 따라 version을 수정
# package.json 파일의 version과 git tag가 생성
npm run release

Reference

• Conventional Commits
• GitHub - commitizen/cz-cli: The commitizen command line utility. #BlackLivesMatter
• Commit History를 효과적으로 관리하기 위한 규약: Conventional Commits | by Joonho Yeom | RIZON Korea | Medium
• https://github.com/conventional-changelog/standard-version
• Conventional Commits | 쿡앱스 기술 블로그
• https://johnny-mh.github.io/post/standard-version-%EA%B8%B0%EB%B0%98-%EC%84%9C%EB%B9%84%EC%8A%A4-%EB%B0%B0%ED%8F%AC%ED%94%84%EB%A1%9C%EC%84%B8%EC%8A%A4
• commitlint/@commitlint/config-conventional at master · conventional-changelog/commitlint · GitHub
• https://medium.com/@jsilvax/automate-semantic-versioning-with-conventional-commits-d76a9f45f2fa
• https://itnext.io/how-to-automate-versioning-and-publication-of-an-npm-package-233e8757a526