/엔지니어/Git / CI·CD/Semantic Versioning + Conven
Git / CI·CD중급UbuntuDebianmacOSsemverconventional-commitschangelog

Semantic Versioning + Conventional Commits + 자동 CHANGELOG

semver 규칙, Conventional Commits 형식, standard-version / release-please로 버전 태그와 CHANGELOG를 자동 생성하는 방법을 설명합니다.

Semantic Versioning 규칙

MAJOR.MINOR.PATCH — 예: 2.4.1

변경 유형올리는 번호예시
하위 호환 버그 수정PATCH2.4.1 → 2.4.2
하위 호환 기능 추가MINOR2.4.1 → 2.5.0
하위 호환 불가 변경MAJOR2.4.1 → 3.0.0
  • 1.0.0 이전은 초기 개발 단계 (파괴적 변경 자유)
  • 프리릴리즈: 1.0.0-alpha.1, 1.0.0-beta.2
  • 빌드 메타: 1.0.0+20250527

Conventional Commits 형식

CODE
<type>(<scope>): <subject>

[body]

[footer]

타입 목록:

타입의미버전 영향
feat새 기능MINOR
fix버그 수정PATCH
docs문서만 변경-
style포매팅 (기능 변화 없음)-
refactor기능 변화 없는 코드 정리-
perf성능 개선PATCH
test테스트 추가·수정-
chore빌드·설정 변경-
ciCI 설정 변경-
BREAKING CHANGE하위 호환 불가MAJOR
Bash
# 예시
git commit -m "feat(auth): OAuth2 로그인 추가"
git commit -m "fix(api): 타임아웃 오류 수정"
git commit -m "feat!: 기존 API 제거"
# 또는 footer에
git commit -m "feat: 새 인증 방식

BREAKING CHANGE: /api/v1/login 엔드포인트 제거됨"

standard-version으로 자동 릴리즈

Bash
npm install --save-dev standard-version
JSON
// package.json
{
  "scripts": {
    "release": "standard-version",
    "release:minor": "standard-version --release-as minor",
    "release:major": "standard-version --release-as major",
    "release:patch": "standard-version --release-as patch"
  }
}
Bash
# 자동으로 버전 bump + CHANGELOG 생성 + git tag
npm run release

# 드라이런 (실제 변경 없이 확인)
npx standard-version --dry-run

# 태그 푸시
git push --follow-tags

GitHub Actions로 자동 릴리즈

YAML
# .github/workflows/release.yml
name: Release

on:
  push:
    branches: [main]

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0      # 전체 히스토리 필요

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Configure Git
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"

      - name: Release
        run: |
          npm ci
          npx standard-version
          git push --follow-tags
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

CHANGELOG.md 예시 출력

MARKDOWN
# Changelog

## [2.5.0] - 2025-05-27
### Features
- **auth:** OAuth2 로그인 추가 (abc1234)

### Bug Fixes
- **api:** 타임아웃 오류 수정 (def5678)

## [2.4.2] - 2025-05-20
### Bug Fixes
- **db:** 연결 누수 수정 (ghi9012)
#semver#conventional-commits#changelog#버전관리#git
편집 안내 · Editorial Note

이 가이드는 AI 도구를 활용해 초안을 구성하고 사람이 명령어·문맥을 검토해 발행했습니다. 운영체제와 도구 버전에 따라 결과가 달라질 수 있으므로 적용 전 공식 문서를 함께 확인하세요. 오류를 발견하시면 이메일로 제보해 주세요.

관련 공식 문서Git 공식 문서

질문 & 답변 (Q&A)

이 가이드에 대해 궁금한 점을 질문해보세요. 확인 후 답변드립니다.