Introduction

효과/효율적으로 release note 및 version 관리를 하기 위한 주요 규격 - Conventional Commits, Semantic Versioning, CHANGELOG.md에 관한 논의이다.

Motivation

  • release note는 내용 상 git log와 겹침. git log와 별개로 release note 작성은 상당히 거추장스러움과 동시에 비효율적인 일.
  • 따라서 git log를 잘만 활용하면 release note 생성은 자동화 가능
  • 그리 비범하지 않은 아이디어인데 이미 open source로 마련되어 있을 듯.

Summary

  • Conventional Commits을 따라 commit log를 작성하면 release note 생성 및 versioning을 자동화할 수 있는 기반이 마련됨.
  • Conventional Commits은 매우 쉽고 단순함.
  • Conventional Commits은 Semantic Versioning(SemVer)과 일반적 CHANGLOG.md 형식과 잘 어울림.
  • Semantic Versioning(SemVer)은 Open Source communities에서 versioning의 de facto 표준으로 통용됨.
  • release note는 CHANGELOG.md란 이름의 파일로 큰 규모의 Open Source communities에서 주로 사용 중. 포맷 표준은 없으나 일반적으로 사용되는 포맷이 있음.

Conventional Commits

Conventional Commits을 사용하면 무엇이 좋은지

https://www.conventionalcommits.org/ko/v1.0.0/#왜-conventional-commits를-사용할까요 에서 추출

  • CHANGELOG를 자동으로 생성하기 위해서
  • (포함된 커밋의 타입에 기반하여) 유의적 버전(Semantic Version)을 자동으로 변경하기 위해서
  • 팀 동료, 타인, 그리고 기타 이해당사자에게 변화의 본질을 전달하기 위해서
  • 빌드와 배포 프로세스를 수행하기 위해서
  • 더 구조화된 커밋 히스토리를 보여줘서 사람들이 프로젝트에 기여하기 더 쉽도록 하기 위해서

(바쁜 분을 위한) Conventional Commits 규격 요약

규격 상세 및 다양한 예제 등은 https://www.conventionalcommits.org/en/v1.0.0/ 을 참조(규격답지 않게 가독성 매우 높고 짧음)

  • 동사 원형으로 시작하는 기존 git commit log 프랙티스 앞에 해당 commit의 성격을 나타내는 타입과 colon(:)을 추가.

    • 예제 : feat: allow provided config object to extend other configs

  • 사용 가능한 타입에는 다음이 있음

    • feat : feature의 약자로 새 기능을 의미. Semantic versioning의 MINOR 에 해당
    • fix : 버그 패치. Semantic versioning의 PATCH 에 해당

  • 타입/범위 뒤에 ! 또는 메시지 footer로 BREAKING CHANGE: 로 시작하는 설명을 붙여 API 하위호환이 없는 변경을 나타냄. Semantic versioning의 MAJOR 에 해당

    • 예제 #1 : feat!: allow provided config object to extend other configs

    • 예제 #2 :

      feat: allow provided config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used for extending other config files
      SHELL

  • 타입 뒤에 ()를 사용하여 적용 범위 지정 가능

    • 예제 : feat(api): allow provided config object to extend other configs

  • 기타 : 상기 2개 타입 이외의 것도 가능. 예로 chore:, refactor: 등이 있을 수 있음. Conventional Commits의 근간이 되는 angular convention에서 정의하는 타입을 추천.

Semantic Versioning (SemVer)

Semantic Versioning을 왜 사용하는지

  • 버전 관리의 명확성: SemVer는 각 버전을 Major, Minor, Patch 세 가지 숫자로 표현하여 단순하고 명확한 버전 관리 체계 제공.
  • 의존성 관리 용이: SemVer는 업데이트의 크기와 종류를 명확하게 구분하여 업데이트의 내용과 기존 소프트웨어와의 호환성 여부를 명확히 함.
  • 작업의 투명성: SemVer에 따른 버전 표기는 프로젝트의 진행 과정과 변경 사항을 투명하게 드러냄 .이는 협업과 정보 교환을 원활하게 함.

Semantic Versioning 규격 요약

https://semver.org/에서 추출

버전을 MAJOR.MINOR.PATCH로 하여,

  1. 기존 버전과 호환 없이 API가 변경되면 MAJOR을 올리고,
  2. 기존 버전과 호환을 유지하면서 새로운 기능이 추가되면 MINOR을 올리고,
  3. 기존 버전과 호환을 유지하면서 버그가 수정되면 PATCH을 올림.

정식 배포 전 버전과 빌드 메타데이터를 위한 라벨이 MAJOR.MINOR.PATCH에 확장으로 붙을 수도 있음

Semantic Versioning 예

  • 3.1.0
  • 1.0.0-alpha.1 (정식 배포 전 라벨 붙은 경우)

CHANGELOG.md

  • 표준은 없으나, 큰 규모의 open source 프로젝트들이 따르는 일반적인 형식이 있음.

  • 표준은 아니나 의미론상 규칙을 제안한 ‘눈에 띄는’ 사이트 keep a changelog (https://keepachangelog.com/en/1.1.0/) 다음은 해당 사이트의 가이드.

    • Changelogs는 사람을 위한 것입니다. 기계를 위한 것이 아닙니다.
    • 모든 단일 버전에 대한 항목이 있어야 합니다.
    • 같은 유형의 변경사항은 모아야 합니다.
    • 버전과 섹션은 연결할 수 있어야 합니다.
    • 최신 버전이 처음에 나옵니다.
    • 각 버전의 릴리즈 날짜를 표시해야 합니다.
    • 시멘틱 버저닝를 따르는지 언급해 주세요.

  • keep a changelog 이외에 CHANGELOG.MD 란 사이트도 유사 내용으로 가이드

  • 마지막으로 Common Changelog 란 사이트도 keep a changelog 의 stricker subset임을 언급하며 유사 내용으로 가이드

    • Common Changelog site link : https://common-changelog.org/#21-file-format
    • 근데 Conventional Commits를 anitipattern으로 논하는 것은 함정(! 근데 Common Changelog는 Conventional Commits에 비교 불가한 수준으로 언급이 안되는지라...)

  • CHANGLELOG.md 파일 예제

큰 규모의 open source 프로젝트들이 따르는 일반적인 형식 요약

  • 파일 이름: CHANGELOG.md
  • 문서 형식: markdown 포맷 기반.
  • 버전 표기: 각 버전이라는 목차를 작성할 때, SemVer에 따라서 vX.Y.Z와 같은 형식으로 버전을 표기.
  • 날짜 표기: 버전 정보 바로 다음에, 괄호 안에 ISO-8601 형식(YYYY-MM-DD)의 날짜 기입.
  • 변경 사항: 각 버전별 변경 사항을 명확히 표시. 기능 추가, 변경 사항, 버그 수정 등의 카테고리를 나누어 각 항목을 목록으로 작성.
  • 최신 버전 우선: 최신 버전이 파일의 가장 상단에 위치.

Comments