본문으로 건너뛰기

오픈 소스는 어떻게 Git Commit 컨벤션을 지켜서 CHANGELOG를 관리하는가

 · reading-time-plural

내가 알고 있던 Git Commit 컨벤션 다른 사람들은 어떻게 사용할까? 오픈 소스 사례를 봐보자

개요​

Git 을 사용하면서 한 번쯤 Commit 메시지를 어떻게 작성해야 할지 고민했던 적이 있을 것이다.

왜 Commit 메시지를 고민할까? 여러 이유가 있겠지만 수정한 의도와 유지 보수를 위함일 것이다. (조금 더 생산적인 마인드로 생각해 보면 메시지를 잘 적으면 팀원이 나에게 어떤 의도를 가지고 수정했는지 물어보지 않을 수 있다!)

관련해서 찾아보면 다들 이러한 고민을 하고 있었고, 많이 발생하는 Case에 대해서 잘 정리된 내용을 볼 수 있을 것이다.

실제로 적용해서 사용하다 보면 내가 정말 잘 사용하고 있는 것이 맞을까? 다른 사람은 어떻게 사용하는지 궁금증이 발생하기 마련인데 남의 회사 코드를 볼 수 없으니… 오픈소스 프로젝트를 레퍼런스 해보자.

또한, Commit 메시지를 잘 작성하면 손쉽게 패치 노트를 작성할 수 있다. 오픈 소스의 Releases를 보면 아래와 같은 형식으로 Git Commit이 쭉 나열되거나 CHANGELOG.md 작성된 것을 볼 수 있는데 어떻게 나열하는지도 봐보자

🚨 fix: ??? 수정 #1801
✨ feat(clipboard): ??? 개발 #1807
⬆️ chore(deps): ??? 버전 업 #1815
📝 docs: ??? 문서 보강 #2055

내가 참고하던 Commit 컨벤션​

라이브러리를 사용하면서 봤던 README.md 중 React Query 가 깔끔하게 Commit 컨벤션이 정리되어 있어서 자주 참고했다.

좋아하던 라이브러리이기도 했고 활발한 오픈소스에서 사용되기에 신뢰가 있었다.

https://github.com/TanStack/query/blob/main/CONTRIBUTING.md#type 에 아래와 같이 작성되어 있다.

type설명
feat새로운 기능
fix버그 수정
docs문서만 변경
style코드의 의미에 영향을 주지 않는 변경 사항(공백, 서식 지정, 세미콜론 누락 등)
refactor버그를 수정하거나 기능을 추가하지 않는 코드 변경
perf성능을 향상시키는 코드 변경
test누락된 테스트 추가 또는 기존 테스트 수정
chore문서 생성과 같은 빌드 프로세스 또는 보조 도구 및 라이브러리 변경

그런데 이건 일부의 Case이고 더 자세히 정리된 내용이 없을까 찾아보았다.

Conventional Commits​

Conventional Commits 를 찾을 수 있었다.

내용을 읽어보니 앵귤러 컨벤션 을 기반의 내용도 등장하고, React Query 에서도 https://github.com/TanStack/query/blob/main/CONTRIBUTING.md#commit-message-conventions 에 따라 Angular Commit Message Conventions 을 따라 한다고 하니 잘 정리된 문서로 확인되었다.

내가 기존에 알고 있던 것과 더불어 Conventional Commits 를 통해 알게 된 것은 아래와 같다.

실제 React Query는 어떻게 사용하는가?​

이제 실제 어떻게 사용되는지 궁금해졌다. 한번 React Query 의 PR 을 살펴보자.

CHANGELOG 작성법​

Git Commit 컨벤션을 지키는 이유 중 하나로 CHANGELOG.md 작성을 자동화하기 위함이라는 내용이 있었다.

CHANGELOG 가 뭘까? changelog 작성법 검색을 통해서 알아낼 수 있었습니다. 핵심은 git commit 컨벤션에 맞게 잘 commit 하면 알아서 type에 맞게 분류해 준다는 것이었습니다.

GitHub Release 와 CHANGELOG 의 차이​

여기서 GitHub Release 와 CHANGELOG 의 차이가 궁금해졌습니다.

prettier-vscode releases 및 CHANGELOG 살펴보기​

이번에도 오픈소스의 실 사례를 찾아보자. 이번 내용을 통해 오픈소스가 어떻게 릴리즈 하는가도 볼 수 있다.

  1. VSCode 1.79 부터 Prettier 확장에서 에러가 발생하여 아래의 issue 를 찾을 수 있었습니다.

  2. 시간이 지나 해당 문제를 Fix 하는 아래의 PR (https://github.com/prettier/prettier-vscode/pull/3030) 이 올라왔는데

    1. 어떤 issue 를 해결하는지 descript 에 서술해 놓았고
    2. Release Note 에 작성할 단위의 Fix 이므로 CHANGELOG.md 에 작성은 하는데 ## 를 Unreleased 으로 작성하더군요
    3. Conventional Commits 에서는 컨벤션을 지켜서 자동으로 하던데 그렇지 않은 오픈소스도 만나볼 수 있었습니다.

  3. 그리고 시간이 조금 지나 위에서 Fix 된 것에 대한 Release 를 위해 CHANGELOG.md 와 프로그램 버전명 을 바꾸는 commit 이 들어왔습니다.

    https://github.com/prettier/prettier-vscode/commit/4c26721421a4989d6308e52d37118320b4f9c117

    https://github.com/prettier/prettier-vscode/releases/tag/v9.14.0

  4. 그리고 Release 가 이뤄졌는데 눈여겨볼 점은 위에서 9.14.0 커밋까지가 아닌 마지막 커밋까지 포함해서 릴리즈 했다는 것입니다.

    1. 릴리즈 된 커밋 을 까보면 알 수 있습니다.

      https://github.com/prettier/prettier-vscode/commit/27a6896e3b31e3a319200d7a799b667d35146b3d

결론​

  • 오픈 소스에서는 커밋 컨벤션을 잘 지켜서 관리되고 있구나
  • CHANGELOG 를 사용해서 Release 를 관리를 다들 하는구나
    • 다만, 자동화가 아닌 사람이 직접 관리하는 Case도 있구나
  • CHANGELOG 는 사람들이 이해할 수 있는 단위로 작성되는구나
    • 이번 예제에서 테스트 환경 등과 같은 부가적인 것도 들어갔는데 CHANGELOG 에 명시하지 않았지만 같이 Release 되었다는 것이 인상 깊었다.

Insight​

git log 보기 편하게 출력하는 방법​

  • git log --pretty="- %s" 입니다.

  • git log --pretty="- %s" > CHANGELOG.md 을 하면 간단하게 CHANGELOG 를 뽑아낼 수 있습니다.

    git log --pretty="- %s" > CHANGELOG.md

    - fix: add utf-8 encoding option to build.gradle
    - test: add test for judging by user input
    - style: add new line at the end of QuizMakerTest.java
    - test: add test for creating new quiz
    - refactor: change class name AnswerBall to Answer
    - feat: compose features
    - feat: add function to repeat or not when it is finished
    - feat: add function to print result of user input
    - refactor: add vo classes to hand values over
    - feat: add function to check if user input is correct
    - feat: add function to read and validate user input
    - feat: add function to create a quiz
    - docs: add function list to implement
    - feat: setup baseball game project

Reference​


도움이 되셨나요? 💁‍♂️
다른 게시물도 있어요. 🐥