Git 메시지 기반 개발 문서 자동 생성 가이드

본 문서는 Git 커밋 메시지를 분석하여 CHANGELOG.md 또는 DEVELOPMENT_DOC.md와 같은 개발 문서를 자동으로 생성하고 관리하는 방법.

1. 개요 (Introduction)

개발 생산성을 높이기 위해서는 변경 사항을 문서화하는 과정이 필수적입니다. 하지만 수동으로 문서를 작성하는 것은 번거롭고 실수가 발생하기 쉽습니다.

해결책: Git 커밋 메시지를 구조화하고, 이를 기반으로 문서를 자동 생성하는 도구를 도입합니다.

왜 git-cliff 인가?

속도: Rust로 작성되어 매우 빠릅니다.
유연성: cliff.toml 파일을 통해 출력 형식을 완벽하게 커스터마이징할 수 있습니다.
범용성: GitHub Actions와 같은 CI/CD 도구와 쉽게 통합됩니다.

2. 전제 조건: Conventional Commits

자동 생성을 위해서는 커밋 메시지가 일정한 규칙을 따라야 합니다. 가장 널리 쓰이는 규칙은 Conventional Commits입니다.

기본 구조:

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

자주 사용하는 Type:

feat: 새로운 기능 추가
fix: 버그 수정
update: 코드 변경 또는 유지보수 (사용자 정의)
docs: 문서 수정
style: 코드 포맷팅, 세미콜론 누락 등 (코드 변경 없음)
refactor: 코드 리팩토링
test: 테스트 코드 추가/수정

3. 핵심 구현 예시 (git-cliff + GitHub Actions)

단계 1: cliff.toml 설정

프로젝트 루트에 cliff.toml 파일을 생성하여 문서의 스타일을 정의합니다.

[changelog]
header = "# Development Documentation\n"
body = """
{% if version %}## [{{ version }}] - {{ timestamp | date(format='%Y-%m-%d') }}{% else %}## [Unreleased]{% endif %}
{% for group, commits in commits | group_by(attribute='group') %}
### {{ group }}
{% for commit in commits %}
- **[{{ commit.author.timestamp | date(format="%Y-%m-%d") }}]** {{ commit.message }} (by {{ commit.author.name }})
{% endfor %}
{% endfor %}
"""

[git]
conventional_commits = true
commit_parsers = [
  { message = "^feat", group = "Features" },
  { message = "^fix", group = "Fixes" },
  { message = "^update", group = "Updates" },
  # ... 기타 설정
]

단계 2: GitHub Actions 워크플로우 설정

.github/workflows/changelog.yml 파일을 생성하여 자동화를 수행합니다.

name: Generate Changelog

on:
  push:
    branches: [master, main]

jobs:
  changelog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # 모든 커밋 히스토리를 가져와야 함

      - name: Generate a changelog
        uses: orhun/git-cliff-action@v4
        with:
          config: cliff.toml
        env:
          OUTPUT: DEVELOPMENT_DOC.md # 결과가 저장될 파일명

      - name: Commit and push changes
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add DEVELOPMENT_DOC.md
          git commit -m "docs: update DEVELOPMENT_DOC.md [skip ci]" || echo "No changes"
          git push

4. 실습 및 활용 (Best Practices)

커밋 메시지 작성 시 주의사항: feat:, fix: 접두사를 엄격히 지킵니다.
로컬 테스트: GitHub Actions에 올리기 전 로컬에 git-cliff를 설치하여 git cliff -o DEVELOPMENT_DOC.md 명령어로 미리 확인해 볼 수 있습니다.
태그 활용: git tag -a v1.0.0 -m "Release v1.0.0"와 git push origin v1.0.0와 같이 태그를 생성하면 버전별로 정리된 문서를 얻을 수 있습니다. 이때 태그 이름은 v로 시작해야 합니다.

5. 결론

Git 메시지 기반의 문서 자동화는 **"코드와 문서의 동기화"**를 보장합니다. 이를 통해 개발자는 코드 작성에만 집중할 수 있으며, 프로젝트의 히스토리를 투명하게 관리할 수 있습니다.