출처: Dev.to

자동 버전 관리와 changelog 생성은 오픈소스와 SaaS 팀에서 복잡한 릴리즈 노트와 수동 태깅을 피하기 위해 실제 프로덕션에서 많이 사용하는 패턴입니다.
다음과 같은 요소를 사용해 깔끔한 시스템을 구축합니다:

🧠 Conventional commits (커밋 메시지 규칙)
🤖 Semantic versioning 자동화
📜 자동 생성 CHANGELOG
🚀 GitHub Actions 워크플로

---

📦 1. 필수 도구 설치 (표준 접근법)

우리는 다음을 사용할 것입니다:

👉 semantic-release (업계 표준)

npm install --save-dev semantic-release @semantic-release/changelog @semantic-release/git @semantic-release/github

Your commits MUST follow this format:

Fix (패치 버전 증가)

fix: resolve navbar bug on mobile

또는

BREAKING CHANGE: remove old auth system

.releaserc.json

{
  // 설정 내용은 여기서 정의합니다.
}

---

📜 4. CHANGELOG 파일 만들기

touch CHANGELOG.md

Start empty:

여기에 모든 주요 변경 사항이 기록됩니다.

---

🚀 5. GitHub Actions 워크플로 (자동 버전 + CHANGELOG)

📁 .github/workflows/release.yml

name: Auto Version & Changelog

on:
  push:
    branches:
      - main

jobs:
  release:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

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

      - name: Install dependencies
        run: npm install

      - name: Run semantic release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: npx semantic-release

메인 브랜치에 푸시하면:

• 커밋을 분석
• 버전 증가 결정:
  • fix → 1.0.1
  • feat → 1.1.0
  • breaking → 2.0.0
• changelog 생성
• Git 태그 생성
• GitHub Release 생성
• CHANGELOG.md 업데이트

📜 7. 자동 생성된 changelog 예시

- 사용자 인증 시스템 추가
- 대시보드 분석 추가
- 모바일에서 네비게이션 바 정렬 수정
- API 타임아웃 문제 수정

🏷️ 8. GitHub Release 예시

GitHub이 자동으로 생성합니다:

Features:
- 사용자 인증 시스템
- 분석 대시보드
Fixes:
- 모바일 네비게이션 바 버그

🔐 9. 필요한 GitHub Secrets

다음이 존재하는지 확인하세요:

추가 설정은 필요하지 않습니다.

---

🧪 10. 실제 워크플로 동작

개발자 흐름:

git commit -m "feat: add dashboard UI"
git push origin main

커밋 유형 감지 (feat)
버전 증가 → 마이너 업데이트
CHANGELOG.md 업데이트
Git 태그 생성 (v1.3.0)
GitHub Release 배포

run: npm publish

🟡 Slack 릴리즈 알림

name: Notify Slack
run: curl -X POST $SLACK_WEBHOOK

🔵 다중 브랜치 릴리즈

{
  // 다중 브랜치 설정 예시
}

---

🟣 CHANGELOG 형식 커스터마이징

다음과 같이 커밋을 그룹화할 수 있습니다:

• Features (기능)
• Fixes (버그 수정)
• Performance (성능 개선)
• Breaking changes (파괴적 변경)

---

⚠️ 12. 흔히 하는 실수

❌ Conventional commits 사용 안 함

→ 버전 관리가 정상적으로 동작하지 않음

❌ 지저분한 커밋 메시지 푸시

fix stuff
update

→ 릴리즈 히스토리가 깨짐

---

🚀