zellyy-finance/docs/semantic-release-linear-guide.md

# Semantic Release Linear 연동 가이드

이 가이드는 semantic-release와 Linear 프로젝트 관리 도구 간의 완전한 연동 시스템에 대해 설명합니다.

## 📋 목차

- [개요](#개요)
- [핵심 기능](#핵심-기능)
- [릴리즈 플로우](#릴리즈-플로우)
- [커밋 컨벤션](#커밋-컨벤션)
- [릴리즈 노트 생성](#릴리즈-노트-생성)
- [Linear 이슈 관리](#linear-이슈-관리)
- [자동화 워크플로우](#자동화-워크플로우)
- [사용 방법](#사용-방법)
- [문제 해결](#문제-해결)

## 개요

Zellyy Finance의 semantic-release는 Linear 이슈 추적 시스템과 완전히 통합되어 있습니다. 이를 통해:

- 커밋 메시지의 Linear 이슈 ID를 자동으로 추적
- Linear 이슈를 기반으로 한 상세한 릴리즈 노트 생성
- 릴리즈 완료 시 관련 Linear 이슈에 자동 알림
- 이슈별 담당자 및 카테고리 정보를 포함한 체계적인 릴리즈 관리

## 핵심 기능

### 1. 자동 Linear 이슈 추출

마지막 릴리즈 이후의 모든 커밋에서 Linear 이슈 ID를 자동으로 추출합니다.

```bash
# 지원되는 이슈 ID 형식
ZEL-123, ZEL-456, ZEL-789
```

### 2. 이슈 기반 릴리즈 노트

Linear 이슈 정보를 기반으로 상세한 릴리즈 노트를 자동 생성합니다.

```markdown
# Release 1.2.0

이번 릴리즈에는 5개의 Linear 이슈가 포함되었습니다.

## ✨ New Features
- **ZEL-123**: 사용자 인증 시스템 구현
  - Assignee: Hansoo Ha

## 🐛 Bug Fixes  
- **ZEL-124**: 로그인 오류 수정
  - Assignee: Developer Name

## 🔗 Linear Issues
- [ZEL-123](https://linear.app/zellyy/issue/ZEL-123) - 사용자 인증 시스템 구현
- [ZEL-124](https://linear.app/zellyy/issue/ZEL-124) - 로그인 오류 수정
```

### 3. 자동 이슈 알림

릴리즈 완료 시 포함된 모든 Linear 이슈에 자동으로 릴리즈 알림 코멘트를 추가합니다.

### 4. 메타데이터 추적

각 릴리즈의 상세 정보를 `releases/` 디렉토리에 JSON 형태로 저장합니다.

```json
{
  "version": "1.2.0",
  "releasedAt": "2024-01-15T10:30:00.000Z",
  "issueCount": 5,
  "categories": {
    "features": 2,
    "bugfixes": 2,
    "improvements": 1,
    "other": 0
  }
}
```

## 릴리즈 플로우

### 1. 자동 릴리즈 (메인 브랜치)

```bash
# main 브랜치에 푸시하면 자동으로 릴리즈 검토
git push origin main
```

**릴리즈 플로우:**
1. **Quality Checks**: 타입 체크, 린트, 테스트 실행
2. **Build Verification**: 웹 및 모바일 빌드 검증
3. **Linear Validation**: 커밋의 Linear 이슈 검증
4. **Semantic Release**: 버전 결정 및 릴리즈 생성
5. **Linear Integration**: Linear 이슈에 릴리즈 알림
6. **Deployment Notification**: 배포 완료 알림

### 2. 수동 릴리즈

```bash
# GitHub Actions에서 수동 트리거
# Actions → Release → Run workflow
# Release type: auto/patch/minor/major 선택
```

### 3. 로컬 테스트

```bash
# 드라이 런 (실제 릴리즈 없이 테스트)
npm run release:dry-run

# Linear 플러그인 테스트
npm run release:test
```

## 커밋 컨벤션

### 기본 형식

```bash
<type>(<scope>): <description> [Linear-Issue-ID]

[optional body]

[optional footer(s)]
```

### 예시

```bash
# 새 기능 (Minor 버전 증가)
feat: implement user authentication [ZEL-123]
feat(auth): add OAuth integration [ZEL-124]

# 버그 수정 (Patch 버전 증가)
fix: resolve login error [ZEL-125]
fix(auth): handle invalid token properly [ZEL-126]

# 성능 개선 (Patch 버전 증가)
perf: optimize database queries [ZEL-127]

# Breaking Change (Major 버전 증가)
feat!: redesign API endpoints [ZEL-128]

BREAKING CHANGE: API endpoints now use v2 format
```

### 지원되는 타입

- **feat**: 새로운 기능 (minor)
- **fix**: 버그 수정 (patch)
- **perf**: 성능 개선 (patch)
- **docs**: 문서 변경 (patch)
- **refactor**: 코드 리팩토링 (patch)
- **test**: 테스트 관련 (no release)
- **build**: 빌드 시스템 (no release)
- **ci**: CI 설정 (no release)
- **chore**: 기타 작업 (no release)

### Linear 이슈 ID 형식

```bash
# 대괄호 안에 이슈 ID (권장)
feat: new feature [ZEL-123]

# 괄호 안에 이슈 ID
fix: bug fix (ZEL-124)

# Closes 키워드 사용
feat: new feature

Closes ZEL-125
```

## 릴리즈 노트 생성

### 자동 카테고리 분류

Linear 이슈들은 제목과 라벨을 기반으로 자동으로 분류됩니다:

- **Features (✨)**: feat, feature 키워드 또는 feature 라벨
- **Bug Fixes (🐛)**: fix, bug 키워드 또는 bug 라벨  
- **Improvements (⚡)**: improve, enhance 키워드 또는 improvement 라벨
- **Other (📋)**: 기타 모든 이슈

### 릴리즈 노트 구조

```markdown
# Release 1.2.0

이번 릴리즈에는 5개의 Linear 이슈가 포함되었습니다.

## ✨ New Features
- **ZEL-123**: 사용자 인증 시스템 구현
  - Assignee: Hansoo Ha
- **ZEL-130**: 대시보드 위젯 추가
  - Assignee: Developer Name

## 🐛 Bug Fixes
- **ZEL-124**: 로그인 오류 수정
  - Assignee: Hansoo Ha

## ⚡ Improvements  
- **ZEL-127**: 데이터베이스 쿼리 최적화
  - Assignee: Developer Name

## 🔗 Linear Issues
- [ZEL-123](https://linear.app/zellyy/issue/ZEL-123) - 사용자 인증 시스템 구현
- [ZEL-124](https://linear.app/zellyy/issue/ZEL-124) - 로그인 오류 수정
- [ZEL-127](https://linear.app/zellyy/issue/ZEL-127) - 데이터베이스 쿼리 최적화
- [ZEL-130](https://linear.app/zellyy/issue/ZEL-130) - 대시보드 위젯 추가
```

## Linear 이슈 관리

### 릴리즈 완료 알림

릴리즈가 성공적으로 완료되면 포함된 모든 Linear 이슈에 다음과 같은 코멘트가 자동으로 추가됩니다:

```markdown
🎉 **릴리즈 완료**: v1.2.0

이 이슈가 포함된 새로운 버전이 릴리즈되었습니다.

**릴리즈 정보:**
- 버전: v1.2.0
- 릴리즈 노트: https://github.com/zellycloud/zellyy-finance/releases/tag/v1.2.0
- 배포 시간: 2024-01-15 19:30:00

**다음 단계:**
- 프로덕션 배포 확인
- 기능 테스트 수행
- 사용자 피드백 모니터링
```

### 이슈 상태 관리

릴리즈에 포함된 이슈들의 상태를 체계적으로 관리할 수 있습니다:

1. **Done**: 개발 완료된 이슈들
2. **Released**: 릴리즈에 포함된 이슈들 (자동 알림으로 확인)
3. **Deployed**: 프로덕션 배포 확인된 이슈들

## 자동화 워크플로우

### GitHub Actions 통합

`.github/workflows/release.yml`에서 전체 릴리즈 프로세스를 자동화합니다:

```yaml
# 트리거 조건
on:
  push:
    branches: [main]  # main 브랜치 푸시 시 자동 릴리즈
  workflow_dispatch:  # 수동 트리거 지원
    inputs:
      release_type:
        type: choice
        options: [auto, patch, minor, major]
```

### 주요 단계

1. **Quality Checks**: 코드 품질 검증
   ```yaml
   - Type check (npm run type-check)
   - Linting (npm run lint)
   - Testing (npm run test:run)
   ```

2. **Build Verification**: 빌드 검증
   ```yaml
   - Web build (npm run build)
   - Mobile sync (npm run mobile:sync)
   ```

3. **Linear Validation**: Linear 이슈 검증
   ```yaml
   - Extract Linear issues from commits
   - Validate issue existence
   - Count and report found issues
   ```

4. **Semantic Release**: 릴리즈 생성
   ```yaml
   - Analyze commits for version bump
   - Generate changelog
   - Create GitHub release
   - Execute Linear integration
   ```

5. **Post-Release**: 사후 처리
   ```yaml
   - Update Linear issues with release info
   - Send deployment notifications
   - Prepare rollback information if needed
   ```

## 사용 방법

### 1. 개발 워크플로우

```bash
# 1. 새 기능 브랜치 생성
git checkout -b feature/ZEL-123-user-auth

# 2. 개발 진행
# ... 코드 작성 ...

# 3. Linear 이슈 ID를 포함한 커밋
git commit -m "feat: implement user authentication [ZEL-123]"

# 4. 기능 브랜치 푸시
git push origin feature/ZEL-123-user-auth

# 5. Pull Request 생성 (제목에 Linear 이슈 ID 포함)
# "feat: User authentication system (ZEL-123)"

# 6. 리뷰 및 승인 후 main 브랜치에 머지
# → 자동으로 릴리즈 프로세스 시작
```

### 2. 릴리즈 확인

```bash
# 릴리즈 로그 확인
# GitHub → Actions → Release 워크플로우 확인

# 생성된 릴리즈 확인
# GitHub → Releases 페이지 확인

# Linear 이슈 업데이트 확인
# Linear에서 해당 이슈의 코멘트 확인
```

### 3. 로컬 테스트

```bash
# 드라이 런으로 릴리즈 시뮬레이션
npm run release:dry-run

# Linear 플러그인 단독 테스트
LINEAR_API_KEY=your-key npm run release:test

# 전체 Linear 통합 테스트
npm run linear:test-workflow -- --linear-api=your-key
```

## 문제 해결

### 자주 발생하는 문제들

#### 1. Linear API 연결 실패

**증상**: `LINEAR_API_KEY not found` 오류

**해결방법**:
```bash
# 1. GitHub Secrets 확인
# Repository Settings → Secrets → LINEAR_API_KEY 존재 확인

# 2. API 키 권한 확인
# Linear Settings → API → Personal API keys 확인

# 3. 로컬 테스트
LINEAR_API_KEY=your-key npm run release:test
```

#### 2. 커밋에서 Linear 이슈를 찾을 수 없음

**증상**: `No Linear issues found in commits`

**해결방법**:
```bash
# 올바른 커밋 메시지 형식 사용
git commit -m "feat: new feature [ZEL-123]"
git commit -m "fix: bug fix (ZEL-456)"

# 커밋 히스토리 확인
git log --oneline --grep="ZEL-"
```

#### 3. Semantic Release 실행 실패

**증상**: `No release type found` 또는 권한 오류

**해결방법**:
```bash
# 1. 커밋 컨벤션 확인
# feat:, fix:, perf: 등 올바른 타입 사용

# 2. GitHub Token 권한 확인
# GITHUB_TOKEN이 올바른 권한을 가지고 있는지 확인

# 3. 브랜치 확인
# main 브랜치에서만 릴리즈 가능
```

#### 4. Linear 이슈에 코멘트 추가 실패

**증상**: `Failed to add comment to ZEL-XXX`

**해결방법**:
```bash
# 1. Linear 이슈 존재 확인
# 해당 이슈가 Linear에 실제로 존재하는지 확인

# 2. API 키 권한 확인
# Write 권한이 있는 API 키인지 확인

# 3. 네트워크 연결 확인
# GitHub Actions에서 Linear API 접근 가능한지 확인
```

### 로그 분석

#### GitHub Actions 로그

```bash
# 1. Repository → Actions 이동
# 2. 실패한 워크플로우 클릭
# 3. 각 단계별 로그 확인

# 주요 확인 사항:
# - Quality Checks: 모든 체크 통과 여부
# - Semantic Release: 버전 결정 및 노트 생성
# - Linear Integration: API 호출 성공 여부
```

#### 로컬 디버깅

```bash
# 상세 로그와 함께 테스트
DEBUG=true npm run release:test

# Linear 통합 전체 테스트
npm run linear:test-workflow -- --verbose

# 릴리즈 메타데이터 확인
cat releases/v*-metadata.json | jq
```

### 복구 방법

#### 릴리즈 실패 시

```bash
# 1. 실패한 릴리즈 삭제 (필요한 경우)
# GitHub → Releases에서 삭제

# 2. Git 태그 정리 (필요한 경우)
git tag -d v1.2.0
git push origin :refs/tags/v1.2.0

# 3. 문제 해결 후 재실행
# main 브랜치에 빈 커밋 푸시하여 재트리거
git commit --allow-empty -m "chore: trigger release"
git push origin main
```

#### Linear 동기화 실패 시

```bash
# 수동으로 Linear 릴리즈 완료 스크립트 실행
node scripts/semantic-release-linear-plugin.cjs success 1.2.0

# 또는 개별 이슈에 수동 코멘트 추가
npm run linear:comment -- --issue-id=ZEL-123 --event=release --action=completed
```

## 모니터링 및 메트릭

### 릴리즈 성과 지표

- **릴리즈 빈도**: 주/월별 릴리즈 횟수
- **이슈 포함률**: 릴리즈당 평균 Linear 이슈 수
- **카테고리 분포**: Features vs Bug Fixes vs Improvements 비율
- **담당자별 기여도**: 이슈 담당자별 릴리즈 참여 현황

### 자동 보고서

`releases/` 디렉토리의 메타데이터를 활용하여 릴리즈 트렌드를 분석할 수 있습니다:

```bash
# 최근 릴리즈 현황 확인
ls -la releases/

# 특정 릴리즈 상세 정보
cat releases/v1.2.0-metadata.json | jq
```

---

이 시스템을 통해 Linear 이슈 추적과 semantic-release가 완벽하게 통합되어 체계적이고 투명한 릴리즈 관리가 가능합니다.