CHANGELOG 자동으로 생성하기 (git-cliff)
changelog는 프로젝트의 버전별 변경사항을 정리한 것이다. 이게 없다면 라이브러리나 프로그램 버전을 올릴 때 git diff를 직접 봐야 하는데 매우 불편하기 때문에 changelog를 잘 만들어놔야 한다.
직접 changelog를 작성하는 것은 번거로운데, git-cliff 등의 changelog 생성기를 이용해 자동으로 만들 수 있다.
이 글에서는 git-cliff를 이용해 changelog를 자동으로 만드는 방법을 알아보자
git-cliff
- docs: https://git-cliff.org/
- repository: https://github.com/orhun/git-cliff
changelog를 생성하는 유틸리티가 git-cliff 말고도 많이 있지만, git-cliff는 유지보수가 잘 되고 있으며 커스터마이징도 용이하고 속도가 빨라 추천한다.
참고로 git-cliff는 Rust로 작성되었다.
설치는 여러 방법으로 할 수 있는데, 예를 들어 homebrew를 사용해 설치하려면 아래 명령어를 사용한다.
brew install git-cliff
다른 설치방법은 installation 페이지를 참고한다.
git-cliff 실행은 git cliff
로 하면 된다.
git-cliff를 이용한 CHANGELOG.md 생성
아래는 예시 프로젝트 링크이다.
아래처럼 tag를 x.x.x 형식으로 만들어 놓았다.
프로젝트에서 git-cliff를 이용하려면 먼저 설정 파일(cliff.toml)을 생성하고, 그 다음 git-cliff 를 실행해야 한다.
--init
옵션을 넣고 git-cliff를 실행하면 기본 설정 파일이 생성된다.
git cliff --init
설정 파일 형식은 TOML이다. 옵션이 상당히 많은데, 전체 옵션별 설명은 Configuration 문서를 참고한다.
changelog를 생성하기 위한 템플릿 엔진은 Tera를 사용하고 있으며, Jinja2와 비슷한 형식으로 사용할 수 있다. Tera 템플릿에 대한 자세한 설명은 문서를 참고한다.
기본적으로 conventional commit 형식에 맞춰 커밋 메시지를 파싱해 changelog를 파싱하기 때문에, 커밋 메시지가 해당 형식으로 작성되지 않았다면 git.conventional_commits
, git.filter_unconventional
항목을 false로 설정해줘야 한다.
나머지 항목은 리파지토리나 커밋 형식에 맞춰 적절히 수정해준다.
# git-cliff ~ default configuration file
# https://git-cliff.org/docs/configuration
#
# Lines starting with "#" are comments.
# Configuration options are organized into tables and keys.
# See documentation for more information on available options.
[changelog]
# changelog header
header = """
# Changelog\n
All notable changes to this project will be documented in this file.\n
"""
# template for the changelog body
# https://keats.github.io/tera/docs/#introduction
body = """
{% if version %}\
## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
{% else %}\
## [unreleased]
{% endif %}\
{% for group, commits in commits | group_by(attribute="group") %}
### {{ group | upper_first }}
{% for commit in commits %}
- {% if commit.breaking %}[**breaking**] {% endif %}{{ commit.message | upper_first }}\
{% endfor %}
{% endfor %}\n
"""
# remove the leading and trailing whitespace from the template
trim = true
# changelog footer
footer = """
<!-- generated by git-cliff -->
"""
# postprocessors
postprocessors = [
# { pattern = '<REPO>', replace = "https://github.com/orhun/git-cliff" }, # replace repository URL
]
[git]
# parse the commits based on https://www.conventionalcommits.org
conventional_commits = true
# filter out the commits that are not conventional
filter_unconventional = true
# process each line of a commit as an individual commit
split_commits = false
# regex for preprocessing the commit messages
commit_preprocessors = [
# { pattern = '\((\w+\s)?#([0-9]+)\)', replace = "([#${2}](<REPO>/issues/${2}))"}, # replace issue numbers
]
# regex for parsing and grouping commits
commit_parsers = [
{ message = "^feat", group = "Features" },
{ message = "^fix", group = "Bug Fixes" },
{ message = "^doc", group = "Documentation" },
{ message = "^perf", group = "Performance" },
{ message = "^refactor", group = "Refactor" },
{ message = "^style", group = "Styling" },
{ message = "^test", group = "Testing" },
{ message = "^chore\\(release\\): prepare for", skip = true },
{ message = "^chore\\(deps\\)", skip = true },
{ message = "^chore\\(pr\\)", skip = true },
{ message = "^chore\\(pull\\)", skip = true },
{ message = "^chore|ci", group = "Miscellaneous Tasks" },
{ body = ".*security", group = "Security" },
{ message = "^revert", group = "Revert" },
]
# protect breaking changes from being skipped due to matching a skipping commit_parser
protect_breaking_commits = false
# filter out the commits that are not matched by commit parsers
filter_commits = false
# regex for matching git tags
tag_pattern = "v[0-9].*"
# regex for skipping tags
skip_tags = "v0.1.0-beta.1"
# regex for ignoring tags
ignore_tags = ""
# sort the tags topologically
topo_order = false
# sort the commits inside sections by oldest/newest order
sort_commits = "oldest"
# limit the number of commits included in the changelog.
# limit_commits = 42
changelog는 기본적으로 stdout에 출력되며, 파일로 출력하려면 -o
옵션을 넣어준다.
# stdout 출력
git cliff
# CHANGELOG.md 파일로 출력
git cliff -o CHANGELOG.md
설정을 약간 수정하고, 출력한 예시는 아래와 같다
# Changelog
All notable changes to this project will be documented in this file.
## [unreleased]
### Miscellaneous Tasks
- Update readme ([#1](https://github.com/vince-test-org/changelog-generator-example/issues/1)) ([5f71f69](https://github.com/vince-test-org/changelog-generator-example/commit/5f71f697e63b200066ee999b4748af412b446210))
## [0.3.0] - 2023-11-24
### Features
- Replace issue link, add commit hash in changelog ([7cb35c9](https://github.com/vince-test-org/changelog-generator-example/commit/7cb35c9735b3955b88d226f7f2340819b7fde059))
### Miscellaneous Tasks
- On push tags ([4a3310f](https://github.com/vince-test-org/changelog-generator-example/commit/4a3310f4b8ea0eb711d9e53f6c24a5b42af36812))
## [0.2.0] - 2023-11-24
### Bug Fixes
- Tag pattern ([92e66a6](https://github.com/vince-test-org/changelog-generator-example/commit/92e66a6da435b425b77c8b58a25e4b7393e201fd))
### Features
- Add changelog workflow ([6f64c17](https://github.com/vince-test-org/changelog-generator-example/commit/6f64c176e61e94cc3a1854902e6bc7035480844d))
## [0.1.0] - 2023-11-24
### Miscellaneous Tasks
- Init ([a3be969](https://github.com/vince-test-org/changelog-generator-example/commit/a3be9697e3b36229190c99da04f9519fab2e069f))
<!-- generated by git-cliff -->
아래처럼 github actions workflow를 만들어서 자동으로 업데이트 할 수도 있다
(아래 예시는 모든 커밋마다 업데이트를 시도해서 실제로 프로젝트에 적용한다면 릴리즈시에만 작동하게 하는 등 수정이 좀 필요하다)
name: Update CHANGELOG
on:
push:
tags:
- '*'
branches:
- main
permissions:
contents: write
jobs:
git-cliff-action:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v3
with:
fetch-depth: 0
- name: Generate a changelog
uses: orhun/git-cliff-action@v2
id: git-cliff
with:
config: cliff.toml
args: --verbose
env:
OUTPUT: CHANGELOG.md
- name: Set github-actions bot config
run: |
git config user.name 'github-actions[bot]'
git config user.email 'github-actions[bot]@users.noreply.github.com'
- name: Commit and push CHANGELOG, only if there are any changes
run: |
if [[ -n $(git status -s) ]]; then
git add CHANGELOG.md
git commit -m "Update CHANGELOG"
git push origin HEAD
fi