zellyy-finance/docs/version-management-guide.md

버전 관리 및 릴리즈 자동화 가이드

개요

Zellyy Finance 프로젝트는 Conventional Commits과 Semantic Release를 사용하여 완전히 자동화된 버전 관리 시스템을 구축했습니다. 커밋 메시지를 기반으로 버전을 자동으로 관리하고, 릴리즈 노트를 생성하며, 모든 플랫폼의 버전을 동기화합니다.

시스템 구성 요소

1. Semantic Release 설정 (.releaserc.json)

{
  "branches": ["main", {"name": "beta", "prerelease": true}],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator", 
    "@semantic-release/changelog",
    "@semantic-release/npm",
    "@semantic-release/github",
    "@semantic-release/exec",
    "@semantic-release/git"
  ]
}

2. 버전 동기화 스크립트 (scripts/sync-versions.cjs)

• package.json 버전을 Android build.gradle과 iOS Info.plist에 동기화
• 시맨틱 버전을 빌드 코드로 변환 (예: 1.2.3 → 10203)
• 검증 모드 지원 (--check 플래그)

3. 릴리즈 후 처리 스크립트 (scripts/release-version.cjs)

• Semantic Release 완료 후 자동 실행
• 모바일 플랫폼 버전 동기화
• Capacitor 동기화

커밋 메시지 규칙 (Conventional Commits)

기본 형식

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

[optional body]

[optional footer]

지원하는 타입과 버전 영향

타입	설명	버전 영향	예시
feat	새로운 기능	Minor (1.0.0 → 1.1.0)	feat: 거래 필터링 기능 추가
fix	버그 수정	Patch (1.0.0 → 1.0.1)	fix: 로그인 오류 수정
perf	성능 개선	Patch (1.0.0 → 1.0.1)	perf: 차트 렌더링 최적화
docs	문서 변경	Patch (1.0.0 → 1.0.1)	docs: API 문서 업데이트
refactor	리팩토링	Patch (1.0.0 → 1.0.1)	refactor: 컴포넌트 구조 개선
revert	되돌리기	Patch (1.0.0 → 1.0.1)	revert: feat: 거래 필터링 기능 제거
style	스타일 변경	없음	style: 코드 포맷팅
test	테스트 추가/수정	없음	test: 로그인 테스트 추가
build	빌드 시스템 변경	없음	build: Webpack 설정 변경
ci	CI 설정 변경	없음	ci: GitHub Actions 업데이트
chore	기타 변경	없음	chore: 의존성 업데이트

Breaking Changes (Major 버전)

Major 버전 증가 (1.0.0 → 2.0.0)를 위해서는 다음 중 하나를 사용:

1. 느낌표 표기법:

   feat!: 새로운 API 인터페이스 도입
   

2. Footer 표기법:

   feat: 사용자 인증 시스템 개편
   
   BREAKING CHANGE: 기존 auth API가 제거되고 새로운 인터페이스로 교체됨
   

릴리즈 프로세스

자동 릴리즈 흐름

graph TD
    A[커밋 & 푸시] --> B[GitHub Actions 트리거]
    B --> C[테스트 실행]
    C --> D[빌드 검증]
    D --> E[Semantic Release 실행]
    E --> F[버전 분석]
    F --> G[릴리즈 노트 생성]
    G --> H[package.json 업데이트]
    H --> I[버전 동기화 스크립트 실행]
    I --> J[모바일 플랫폼 동기화]
    J --> K[Git 커밋 & 태그]
    K --> L[GitHub Release 생성]
    L --> M[앱스토어 배포]

1. 개발 단계

# 기능 브랜치에서 개발
git checkout -b feature/new-transaction-filter

# 커밋 (Conventional Commits 규칙 준수)
git commit -m "feat: 거래 내역 필터링 기능 추가

사용자가 날짜, 카테고리, 금액 범위로 거래를 필터링할 수 있는 기능을 추가했습니다."

# PR 생성 후 main 브랜치에 머지

2. 자동 릴리즈 (main 브랜치 푸시 시)

# GitHub Actions에서 자동 실행:
# 1. 테스트 & 빌드
# 2. Semantic Release
# 3. 버전 업데이트 (1.0.0 → 1.1.0)
# 4. 릴리즈 노트 생성
# 5. GitHub Release 생성
# 6. 앱스토어 배포

릴리즈 노트 형식

자동 생성되는 릴리즈 노트 예시:

# [1.1.0](https://github.com/user/repo/compare/v1.0.0...v1.1.0) (2024-01-15)

## ✨ Features

* 거래 내역 필터링 기능 추가 ([a1b2c3d](https://github.com/user/repo/commit/a1b2c3d))
* 다크 모드 지원 ([e4f5g6h](https://github.com/user/repo/commit/e4f5g6h))

## 🐛 Bug Fixes

* 로그인 세션 만료 오류 수정 ([i7j8k9l](https://github.com/user/repo/commit/i7j8k9l))

## ⚡ Performance Improvements

* 차트 렌더링 성능 50% 개선 ([m0n1o2p](https://github.com/user/repo/commit/m0n1o2p))

버전 동기화

플랫폼별 버전 관리

플랫폼	파일	버전 필드	예시 값
Web	package.json	version	"1.2.3"
Android	android/app/build.gradle	versionName, versionCode	"1.2.3", 10203
iOS	ios/App/App/Info.plist	CFBundleShortVersionString, CFBundleVersion	"1.2.3", 10203

버전 코드 변환 규칙

// "1.2.3" → 10203
function versionToCode(version) {
  const [major, minor, patch] = version.split('.').map(Number);
  return major * 10000 + minor * 100 + patch;
}

수동 버전 동기화

# 모든 플랫폼 버전 동기화
npm run version:sync

# 버전 일관성 검사
npm run version:check

# 릴리즈 후 처리 (일반적으로 자동 실행)
npm run version:post-release

GitHub Actions 설정

Workflow 트리거

on:
  push:
    branches: [main]        # 자동 릴리즈
    tags: ['v*']           # 수동 릴리즈
  pull_request:
    branches: [main]        # 테스트만 실행

주요 단계

1. Test & Lint: 코드 품질 검증
2. Build Web: 웹 앱 빌드
3. Build Mobile: Android/iOS 앱 빌드
4. Release: Semantic Release 실행
5. Deploy: 앱스토어 자동 배포

환경별 설정

Beta 릴리즈 (베타 브랜치)

# 베타 브랜치로 푸시하면 prerelease 생성
git checkout -b beta
git push origin beta
# → v1.1.0-beta.1 릴리즈 생성

핫픽스 릴리즈

# main에서 직접 핫픽스
git checkout main
git commit -m "fix: 긴급 보안 패치"
git push origin main
# → 자동으로 v1.0.1 릴리즈 생성

모니터링 및 디버깅

릴리즈 상태 확인

# 최신 릴리즈 정보
gh release list

# 특정 릴리즈 상세 정보  
gh release view v1.1.0

# GitHub Actions 실행 상태
gh run list --workflow=mobile-build.yml

일반적인 문제 해결

1. 버전 동기화 실패

# 수동으로 버전 확인
npm run version:check

# 문제가 있으면 수동 동기화
npm run version:sync

2. Semantic Release 실패

# 커밋 메시지 형식 확인
git log --oneline -5

# 수동으로 semantic-release 실행 (로컬)
npx semantic-release --dry-run

3. 모바일 빌드 실패

# Android 버전 확인
grep -E "versionCode|versionName" android/app/build.gradle

# iOS 버전 확인 (macOS only)
/usr/libexec/PlistBuddy -c "Print :CFBundleShortVersionString" ios/App/App/Info.plist

베스트 프랙티스

1. 커밋 메시지 작성

✅ 좋은 예시:

feat(auth): OAuth 2.0 로그인 지원 추가

Google, GitHub OAuth 프로바이더를 통한 소셜 로그인 기능을 구현했습니다.
- Google OAuth 2.0 클라이언트 설정
- GitHub OAuth 앱 연동  
- 기존 이메일 로그인과 호환성 유지

Closes #123

❌ 나쁜 예시:

update login
fix bug
change ui

2. 릴리즈 전 체크리스트

• 모든 테스트 통과
• 타입 체크 통과
• 린트 검사 통과
• 빌드 검증 완료
• 브레이킹 체인지 문서화
• 버전 호환성 확인

3. 긴급 상황 대응

# 문제가 있는 릴리즈 되돌리기
git revert <commit-hash>
git commit -m "revert: v1.1.0 롤백 - 로그인 오류"
git push origin main
# → 자동으로 v1.1.1 패치 릴리즈 생성

---

이 가이드는 Zellyy Finance의 자동화된 버전 관리 시스템의 완전한 참조 문서입니다. 추가 질문이나 문제가 있으면 개발팀에 문의하세요.