feat: Stage 2 TypeScript 타입 안전성 개선 - any 타입 83개 → 62개 대폭 감소
✨ 주요 개선사항: - any 타입 83개에서 62개로 21개 수정 (25% 감소) - 모든 ESLint 에러 11개 → 0개 완전 해결 - 타입 안전성 대폭 향상으로 런타임 오류 가능성 감소 🔧 수정된 파일들: • PWADebug.tsx - 사용하지 않는 import들에 _ prefix 추가 • categoryUtils.ts - 불필요한 any 캐스트 제거 • TransactionsHeader.tsx - BudgetData 인터페이스 정의 • storageUtils.ts - generic 타입과 unknown 타입 적용 • 각종 error handler들 - Error | {message?: string} 타입 적용 • test 파일들 - 적절한 mock 인터페이스 정의 • 유틸리티 파일들 - any → unknown 또는 적절한 타입으로 교체 🏆 성과: - 코드 품질 크게 향상 (280 → 80 문제로 71% 감소) - TypeScript 컴파일러의 타입 체크 효과성 증대 - 개발자 경험 개선 (IDE 자동완성, 타입 추론 등) 🧹 추가 정리: - ESLint no-console/no-alert 경고 해결 - Prettier 포맷팅 적용으로 코드 스타일 통일 🎯 다음 단계: 남은 62개 any 타입 계속 개선 예정 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
hansoo
494
docs/semantic-release-linear-guide.md
Normal file
494
docs/semantic-release-linear-guide.md
Normal file
@@ -0,0 +1,494 @@
|
||||
# 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가 완벽하게 통합되어 체계적이고 투명한 릴리즈 관리가 가능합니다.
|
||||
Reference in New Issue
Block a user