[사내발표] CHANGELOG 자동화하기

( 이 글은 사내에서 발표한 자료를 바탕으로 작성했습니다.  )

 

개인 프로젝트 혹은 다른 동료와 협업을 할 때 각 버전에 맞는 변경사항을 시간순서대로 작성하기 위해 우리는 CHANGELOG.md 파일을 이용하고 있습니다. 덕분에 기계가 아닌 사람들(개발자 혹은 User)이 해당 프로젝트의 각 릴리즈 버전 간의 차이점을 한눈에 파악해 어떤 점이 왜 바뀌었는지 명확하게 알 수 있습니다.

 

기계가 아닌 사람이 필요로 하기 때문인지는 몰라도 매번 프로젝트의 버전이 바뀔 때마다 직접 손으로 작성합니다. 버전을 드문드문 (예를 들면 2주에 한 번 정도..)변경한다면 불편함이 없겠지만, 팀원이 많거나 FEATURE/FIX 작업이 많을 때 3일에 한 번 혹은 하루에 한 번씩 버전을 변경하는 때도 있습니다. (최근 TF에 버그 수정 및 기능이 많이 추가되면서 CHANGELOG를 꽤 많이 건드렸네요.) 단순하게 CHANGELOG만 변경하는 것에서 끝나는 게 아니라 직접 PR을 열어 title, description을 작성하고 Approve까지 받아야 하니 여간 번거롭지 않을 수 없는데요.

 

잘못된 커밋이 있을 수도 있기 때문에 팀원 Approve는 꼭 필요한 단계라고 생각해도, 이전 단계(CHANGELOG.md 파일에 변경사항을 직접 추가하고 GitHub에 들어가서 PR을 생성하는 단계)는 직접 손으로 하는 게 아니라 자동으로 컴퓨터한테 전가하여 시간을 단축하면 어떨까?라는 생각이 불쑥 들더군요.. (반복적인 작업을 싫어하는 개발자분들에게 여쭤봅니다. 저만 그런 것은 아니죠..?) 그래서 찾아봤습니다. HOW TO Automation CHANGELOG & PR!

 

우선, 장안의 화제인 ChatGPT에게 괜찮은 Tool이 있는지 물어봤습니다.

 

 

마음에 드는 선택지가 없어 더 알려달라고 했습니다.

 

 

총 10개 정도의 선택지를 추천해줬고, 9번째에 있는 release-please가 괜찮아 보였습니다. Google API여서 그런지 믿음직해 보였고, 이슈도 활발하게 일어나고 있어 유지보수가 잘 되겠다고 생각했습니다.

 

여담으로 첫 번째 선택지에 Conventional Commits가 있는데, 이는 커밋 메세지를 일관되고 표준화된 방법으로 작성하도록 유도하는 convention입니다. (release-please는 이를 컨벤션으로 채택했습니다. 이와 비슷한 tool 중에 standard-version도 마찬가지로 Conventional Commits를 convention으로 채택했는데 현재는 deprecated 되었고, 대신 release-please를 추천해주고 있습니다.)

 

우선, release-please를 setting하려면 3가지 방법이 있습니다. (GitHub Action(recommended), Running as CLI, Install the GitHub App) 이 중 recommended인 GitHub Action을 선택했습니다. 이제 .github/workflows/release-please.yml을 추가하면 main branch에 push 될 때마다 동작합니다. (Configuration은 release-please-action을 참고해주세요!)

 

on:
  push:
    branches:
      - main
name: release-please
jobs:
  release-please:
    runs-on: ubuntu-latest
    steps:
      - uses: google-github-actions/release-please-action@v3
        with:
          release-type: node
          package-name: release-please-action

 

PR을 main으로 merge하게 되면 release-please Action이 실행되고 자동으로 release 관련 PR이 생성됩니다. 해당 PR에는 커밋로그를 기반으로 CHANGELOG에 자동으로 추가되고 package.json의 version은 다음 버전으로 올라가 있죠.

 

 

복잡할 줄 알았는데 생각보다 간단하게 끝났습니다. 조금만 더 살펴볼까요? 우리가 자주 사용하는 TF의 CHANGELOG.md에도 자동화 기능을 적용해보고 싶었습니다.

 

lerna에서 CHANGELOG.md를 변경하는 방법은 lerna-changelog를 이용하는 방법과 lerna version --conventional-commits명령어를 이용하는 방법이 있습니다. 두 방식 모두 Git commit History를 기반으로 diff를 분석하는 것은 같지만, lerna-changelog는 CHANGELOG.md만 변경하고 lerna version --conventional-commits는 Conventional Commits 사양을 기반으로 CHANGELOG.md변경과 새로운 패키지 버전을 publish 할 수 있다는 것에 차이점이 있습니다.

 

TF의 npm run version 커맨드는 lerna version --no-push --force-publish script를 사용하고 있었으므로 이와 비슷한 두 번째 방법을 사용해봅시다.

💡 잠깐! --no-push --force-publish은 무엇일까요? 🤔

1. 기본적으로 lerna version은 commit과 tagged changes를 git remote에 푸시하지만, --no-push 명령어를 통해 이를 비활성화 할 수 있습니다.
2. 기본적으로 lerna는 diff가 없을 때 version을 update하거나 패키지를 publish하지 않는 반면, --force-publish 명령어를 사용하여 특정 패키지나 *를 사용하여 전체 패키지를 변경사항이 없어도 강제로 publish 할 수 있습니다. 이는 최근 업데이트 되지 않은 패키지에 실제 변경 점이 없음에도 hotfix, security update를 적용하고 싶을 때 유용합니다.

(다시 본론으로 돌아와서) script를 "testversion": "lerna version --conventional-commits"로 변경 후 npm run testversion을 입력했습니다. 터미널에서 MINOR update prompt가 나오는군요. (저의 마지막 커밋 메세지는 feat: constant 추가 였습니다.)

 

 

기존에 사용하던 lerna version ...와 마찬가지로 lerna version --conventional-commits 커맨드도 패키지의 버전을 업데이트 하지만, 추가로 CHANGELOG.md 파일도 자동으로 업데이트 됩니다. 하지만 특정 패키지의 CHANGELOG.md가 아닌 모든 패키지의 CHANGELOG.md가 업데이트 되는군요..

 

 

아쉽게도 "lerna version --conventional-commits"는 특정 패키지 업데이트 버전이 아니라 저장소 여러 패키지에 대한 버전 업데이트를 관리하는 데 사용되는 명령이기 때문에 특정 CHANGELOG.md만 업데이트를 하는 방법은 없습니다. (단순하게 CHANGELOG만 변경하려면 위에서 언급한 lerna-changelog를 이용하는 방법을 사용해야합니다.)

 

이어서 CHANGELOG.md 파일을 살펴보니 conventionalcommits 컨벤션 기준을 충족하는 커밋 메세지들이 추가된 모습을 볼 수 있었습니다. (해당 PR의 commit도 CHANGELOG에 반영이 잘 되었군요.) 그러나, TF의 경우 conventionalcommits 컨벤션이 아닌 자체 컨벤션으로 작성되다 보니 기존 양식과 달랐습니다.

 

 

이렇게 하여 개인 repo와 monorepo 내부 패키지를 업데이트하고 CHANGELOG 파일을 자동화하는 방법을 살펴보았습니다. 어땠나요? 매번 손으로 직접 CHANGELOG를 채우다가 commit log를 자동으로 추가해주니 편해보이지 않나요? 그러나 자동화를 도입하는 것은 장점만 있는것은 아닙니다. 그럼 장, 단점을 함께 살펴볼까요?

Pros 🙂

1. Automation: 커밋 로그를 분석하여 자동으로 release하기 때문에 시간을 절약하고 human error를 줄일 수 있습니다.
2. Consistency: Conventional Commits이 기본사양이므로, 특정 프로젝트에 익숙하지 않은 개발자도 코드베이스에 대한 변경 사항을 쉽게 이해할 수 있습니다.
3. Improved collaboration: 개발자가 더욱 상세하고 유익한 커밋 메시지를 제공하도록 권장하여 팀 구성원 간의 협업을 개선하고 code review를 쉽게 합니다.
4. Clear semantic meaning: 특정 키워드(e.g. BREAKING CHANGE, feat, fix...)를 사용하여 명확하게 의미를 제공하고 issue tracking에 도움을 줄 수 있습니다.

Cons 🙁

1. Rebuilding CHANGELOG template: 12.11.0 버전까지 작성되었던 CHANGELOG의 template를 모두 변경하고 다른 패키지의 CHANGELOG를 새로 추가해야 합니다. 여러 개의 CHANGELOG는 한 개의 CHANGELOG보다 맥락을 파악하는데 시간이 더 소요됩니다.
2. Learning curve: Conventional Commits에 익숙해지기 위해 해당 문서를 읽고 시간을 투자해야 합니다.
3. Strict format: 형식이 엄격하므로 개발자가 commit을 한번 할 때 세심하게 주의를 기울여야 합니다. 이 때문에 개발 프로세스에 약간의 overhead가 생길 수 있습니다
4. Customization limitations: Conventional Commits을 기본 format으로 적용하기 때문에 특정/예외 상황에 유연하게 대처하기 어렵습니다.

 

정리한 내용을 토대로 제 사견을 조심스럽게 말씀드리면 TF에 "lerna version --conventional-commits"를 도입하는 것은 대체로 어려움이 따를 것 같습니다. (Pros & Cons 글을 보니 단점이 더 커보입니다.) 그리고 규모가 큰 조직보다는 막 시작한 스타트업에 더 어울리지 않나 싶습니다. (중간에 자동화 migration 하는것보다 처음부터 CHANGELOG를 도입한다면 괜찮았을 텐데 말이죠..!)

지금까지 CHANGELOG 자동화 도입방법을 살펴봤는데, 어떠신가요? 당장 repo에 도입하고 싶으신가요? 아니면 더 다양한 기능이 나올 때까지 지켜봐야할까요? 여러분들의 의견을 자유롭게 말씀해주세요.

 

이만 발표를 마치겠습니다. 긴 발표 들어주셔서 감사합니다. 🙇🏾‍♂️ 🙇🏾‍♂️

 

### Reference

1. 체인지로그 - Wiki
2. release-please
3. conventionalCommits