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

Semantic Release Linear 연동 가이드

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

📋 목차

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

개요

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

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

핵심 기능

1. 자동 Linear 이슈 추출

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

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

2. 이슈 기반 릴리즈 노트

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

# 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 형태로 저장합니다.

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

릴리즈 플로우

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

# 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. 수동 릴리즈

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

3. 로컬 테스트

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

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

커밋 컨벤션

기본 형식

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

[optional body]

[optional footer(s)]

예시

# 새 기능 (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 형식

# 대괄호 안에 이슈 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 (📋): 기타 모든 이슈

릴리즈 노트 구조

# 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 이슈에 다음과 같은 코멘트가 자동으로 추가됩니다:

🎉 **릴리즈 완료**: 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에서 전체 릴리즈 프로세스를 자동화합니다:

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

주요 단계

1. Quality Checks: 코드 품질 검증

   - Type check (npm run type-check)
   - Linting (npm run lint)
   - Testing (npm run test:run)
   

2. Build Verification: 빌드 검증

   - Web build (npm run build)
   - Mobile sync (npm run mobile:sync)
   

3. Linear Validation: Linear 이슈 검증

   - Extract Linear issues from commits
   - Validate issue existence
   - Count and report found issues
   

4. Semantic Release: 릴리즈 생성

   - Analyze commits for version bump
   - Generate changelog
   - Create GitHub release
   - Execute Linear integration
   

5. Post-Release: 사후 처리

   - Update Linear issues with release info
   - Send deployment notifications
   - Prepare rollback information if needed
   

사용 방법

1. 개발 워크플로우

# 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. 릴리즈 확인

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

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

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

3. 로컬 테스트

# 드라이 런으로 릴리즈 시뮬레이션
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 오류

해결방법:

# 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

해결방법:

# 올바른 커밋 메시지 형식 사용
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 또는 권한 오류

해결방법:

# 1. 커밋 컨벤션 확인
# feat:, fix:, perf: 등 올바른 타입 사용

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

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

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

증상: Failed to add comment to ZEL-XXX

해결방법:

# 1. Linear 이슈 존재 확인
# 해당 이슈가 Linear에 실제로 존재하는지 확인

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

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

로그 분석

GitHub Actions 로그

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

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

로컬 디버깅

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

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

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

복구 방법

릴리즈 실패 시

# 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 동기화 실패 시

# 수동으로 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/ 디렉토리의 메타데이터를 활용하여 릴리즈 트렌드를 분석할 수 있습니다:

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

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

---

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