Git Versioning 및 CHANGELOG.md 생성 자동화

많은 오픈소스 프로젝트에서 CHANGELOG.md와 같은 파일을 통해 명시적으로 버전을 관리한다. 현재 개발 중인 프로젝트에서도 이슈 트래킹을 좀 더 수월하게 하고자 이를 적용하기로 했다.

 

Lerna와 standard-version 사이에서 고민하였으나 standard-version가 versioning에 초점이 맞춰져 있는 것에 비해 Lerna는 Mono-Repo를 위한 패키징에 초점이 맞춰져있어 상대적으로 다양한 기능이 많았으나 그만큼 더 무거워 Standard-Version을 채택했다. Github을 사용하는 경우에는 CHANGELOG.md 파일을 만드는 방식이 아닌 Github에서 제공하는 Release를 활용하기도 한다. (standard-version에서도 Github를 사용할 경우 github-actions를 활용한 Release Please를 사용하는 것을 권장한다.)

 

Standard-Version

standard-version는 2가지 개념을 기반으로 Versioning을 진행한다.

---

Semantic Versioning

Semantic Versioning은 오픈 소스 생태계에서 통일된 Version 규칙을 위해 만들어졌다. 이를 통해 오픈 소스는 Versioning 만으로 수정사항과 호환성을 확인할 수 있다. Versioning의 대략적인 규칙은 다음과 같다.

 

1. 버전은 ${Major Version}.${Minor Version}.${Patches}으로 이루어져 있고 모든 버전은 1씩 증가한다.

2. Patches는 버그 수정이 있지만 기능적인 변화가 없을 때 증가한다.

3. Minor Version은 새로운 기능이 추가되었지만 기존의 기능과 호환성이 유지될 때 증가한다.

4. Major Version은 새로운 기능, 혹은 기존의 기능 중 하나라도 이전 버전을 호환하지 않을 때 증가한다.

 

Semantic Versioning은 Github의 공동 창업자가 직접 기존의 방법들을 기반으로 제안했다고 한다.

Semantic Versioning

---

Conventional Commits

Conventional Commits는 커밋 메시지를 간단한 규칙으로 생성하여 커밋 로그 자체도 깔끔하게 만듬과 동시에 이를 통해 자동화를 가능하게 해준다. Convention Commits Spec은 다음과 같다.

 

1. type에는 fix: 혹은 feat: 을 사용해 해당 커밋의 종류를 명시할 수 있다. (@commitlint/config-conventional에서는 흔히 사용하는 build:, chore: 등의 type도 사용이 가능하다.)

2. type 뒤에 !을 붙이거나 footer에 BREAKING CHANGE를 작성하여 해당 커밋의 이전 버전 호환성을 명시할 수 있다.

<type>[optional scope]: <description>
[optional body]
[optional footer(s)]

---

Standard-Version Setting

1. Conventional Commits Spec에 맞춰 커밋 메시지를 작성하기 위해 commitlint 및 husky 세팅(Optional)

1-1. 설치

yarn add -D husky @commitlint/{config-conventional,cli}

 

1-2. root 폴더에 commitlint.config.js 파일 생성

module.exports = {extends: ['@commitlint/config-conventional']}

 

1-3. husky로 git hook 세팅

yarn husky install
yarn husky add .husky/commit-msg "yarn commitlint --edit $1"

이제 커밋 메시지를 Conventional하게 작성하지 않으면 lint 오류가 발생한다.

2. Standard-Version 세팅

2-1. 설치

yarn add -D standard-version

 

2-2. root 폴더에 .versionrc 파일 생성

{
  "types": [
    { "type": "chore", "section": "Others", "hidden": false },
    { "type": "revert", "section": "Reverts", "hidden": false },
    { "type": "feat", "section": "Features", "hidden": false },
    { "type": "fix", "section": "Bug Fixes", "hidden": false },
    {
      "type": "improvement",
      "section": "Feature Improvements",
      "hidden": false
    },
    { "type": "docs", "section": "Docs", "hidden": false },
    { "type": "style", "section": "Styling", "hidden": false },
    { "type": "refactor", "section": "Code Refactoring", "hidden": false },
    { "type": "perf", "section": "Performance Improvements", "hidden": false },
    { "type": "test", "section": "Tests", "hidden": false },
    { "type": "build", "section": "Build System", "hidden": false },
    { "type": "ci", "section": "CI", "hidden": false }
  ]
}

위의 파일은 @commitlint/config-conventional에 포함된 type을 기반으로 만들었고 hidden을 통해 원하지 않는 changelog를 숨길 수 있다.

 

2-3. package.json에 repository 위치 세팅

yarn init

package.json에 현재 바라보는 repository가 명시되어 있지 않다면 yarn init을 통해 이를 명시해둔다.

 

2-4. package.json에 script 추가

{
  "scripts": {
    "release": "standard-version"
  }
}

이제 yarn release를 통해 새로운 changelog를 생성할 수 있다.

 

2-5. 초기 CHANGELOG.md 파일 생성

yarn release --first-release

first release 속성을 이용해 초기 로그를 생성한다.

3. yarn release 자동화

 

Issue 1: tag already exists 오류 발생

standard-version을 통해 version을 업데이트 할 경우 package.json을 기반으로 git tag가 함께 생성이 된다.

이때 생성되는 git tag는 changelog와 package.json을 롤백해도 사라지지 않기 때문에 다시 해당 태그로 release를 할 경우 git tag가 겹쳐서 발생한다.

git tag -d ${targetVersion}

 

겹치는 git tag를 삭제 후 다시 시도해보자.

 

Issue 2: release 시에 CHANGELOG.md가 Update되지 않고 계속해서 쌓이는 경우

Retrieve the current version of your repository by looking at packageFiles, falling back to the last git tag.

초기 세팅 후 release를 하고 테스트를 하면 CHANGELOG.md가 계속해서 첫 Commit부터 쌓이는 경우가 있다.

standard-version에서는 package.json의 repository 속성을 기반으로 현재 버전을 확인하기 때문에 yarn init등을 통해서 세팅해줘야 정상적으로 changelog가 업데이트 된다.

 

 

참고:

https://www.conventionalcommits.org/ko/v1.0.0/

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/

standard-version을 이용한 배포, 롤백 전략 - JOHNNY DEV

https://feel5ny.github.io/2021/02/23/standard-version/

웹 버저닝과 배포내역관리 (feat. standard-version)

https://yogae.tistory.com/25

commit message 관리 - conventional commit