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

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

## 개요

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

## 시스템 구성 요소

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

```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가 제거되고 새로운 인터페이스로 교체됨
   ```

## 릴리즈 프로세스

### 자동 릴리즈 흐름

```mermaid
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. 개발 단계

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

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

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

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

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

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

## 릴리즈 노트 형식

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

```markdown
# [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` |

### 버전 코드 변환 규칙

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

### 수동 버전 동기화

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

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

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

## GitHub Actions 설정

### Workflow 트리거

```yaml
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 릴리즈 (베타 브랜치)

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

### 핫픽스 릴리즈

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

## 모니터링 및 디버깅

### 릴리즈 상태 확인

```bash
# 최신 릴리즈 정보
gh release list

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

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

### 일반적인 문제 해결

#### 1. 버전 동기화 실패

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

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

#### 2. Semantic Release 실패

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

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

#### 3. 모바일 빌드 실패

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

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

## 베스트 프랙티스

### 1. 커밋 메시지 작성

✅ **좋은 예시:**
```bash
feat(auth): OAuth 2.0 로그인 지원 추가

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

Closes #123
```

❌ **나쁜 예시:**
```bash
update login
fix bug
change ui
```

### 2. 릴리즈 전 체크리스트

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

### 3. 긴급 상황 대응

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

---

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