Move directory
This commit is contained in:
wbsong111
@@ -0,0 +1,243 @@
|
||||
# LLM Summarizer + Docs Updater 설계
|
||||
|
||||
## 1. 개요
|
||||
|
||||
Structured Diff JSON과 Breaking Change 판단 결과를 입력받아 자연어 업그레이드 주의사항 문서를 생성하고,
|
||||
해당 차트 버전의 `CUSTOM-README.md`에 반영한다.
|
||||
|
||||
> LLM의 유일한 역할: Structured JSON → Markdown 문서 변환. Diff 생성이나 Breaking 판단은 수행하지 않는다.
|
||||
|
||||
---
|
||||
|
||||
## 2. LLM Summarizer
|
||||
|
||||
### 2.0 실행 조건
|
||||
- `generate_upgrade_doc`은 **항상 실행**한다 (breaking 여부 무관).
|
||||
- `breaking=true` → LLM을 사용하여 `custom-values.yaml` 수정 방법을 포함한 상세 가이드 생성.
|
||||
- `breaking=false` → 템플릿 기반 간단 요약 생성 (LLM 미호출).
|
||||
|
||||
> 카탈로그는 신규 배포를 위한 차트 보관소이므로, breaking 여부와 무관하게 모든 업그레이드에 주의사항 기록이 필요하다.
|
||||
|
||||
### 2.1 입력
|
||||
|
||||
```json
|
||||
{
|
||||
"chart": "airflow",
|
||||
"from_version": "1.2.3",
|
||||
"to_version": "1.3.0",
|
||||
"values": { ... },
|
||||
"templates": { ... },
|
||||
"crd": { ... },
|
||||
"dependencies": { ... },
|
||||
"breaking": true,
|
||||
"severity": "high",
|
||||
"breaking_reasons": [
|
||||
{
|
||||
"type": "values_key_removed",
|
||||
"key": "ingress.enabled",
|
||||
"detail": "custom-values.yaml에서 사용 중인 key가 삭제됨 — 수정 필요"
|
||||
}
|
||||
],
|
||||
"warnings": [
|
||||
{
|
||||
"type": "service_port_changed",
|
||||
"resource": "Service/airflow-webserver",
|
||||
"detail": "port changed from 8080 to 8081"
|
||||
}
|
||||
],
|
||||
"docs_context": {
|
||||
"CUSTOM-README.md": "..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> dip-catalog 구조에서는 버전 디렉토리 내 `CUSTOM-README.md` 내용을 `docs_context`로 제공한다.
|
||||
|
||||
### 2.2 Prompt 설계
|
||||
|
||||
```
|
||||
당신은 Kubernetes Helm 업그레이드 주의사항 문서를 작성하는 전문가입니다.
|
||||
|
||||
두 Helm 차트 버전 간 변경점을 담은 Structured Diff JSON이 제공됩니다.
|
||||
이 카탈로그는 신규 배포를 위한 것이며, custom-values.yaml 수정 필요 여부가 핵심입니다.
|
||||
|
||||
## 작업
|
||||
1. 핵심 변경 사항을 평문으로 요약합니다.
|
||||
2. custom-values.yaml 수정이 필요한 항목(breaking_reasons)을 상세히 설명합니다.
|
||||
3. 신규 배포 시 참고할 주의사항(warnings)을 기록합니다.
|
||||
4. 아래 형식의 간결한 Markdown 문서를 생성합니다.
|
||||
|
||||
## 규칙
|
||||
- 입력 JSON에 없는 내용은 절대 추가하지 마세요.
|
||||
- 추측하지 마세요.
|
||||
- docs_context는 보조 설명에만 사용하고, diff에 없는 변경을 추가하지 마세요.
|
||||
- errors가 있으면 분석이 불완전할 수 있음을 명시하세요.
|
||||
- 배포 담당자가 바로 참고할 수 있도록 명확하게 작성하세요.
|
||||
|
||||
## 출력 형식
|
||||
아래 Markdown 구조를 정확히 지키세요 (`## {to_version}` 헤더는 포함하지 마세요 — `update_docs_file`이 관리):
|
||||
|
||||
### 변경 요약
|
||||
- from_version: <from_version>
|
||||
- to_version: <to_version>
|
||||
- <핵심 변경 사항 bullet points>
|
||||
|
||||
### custom-values.yaml 수정 필요 항목
|
||||
<breaking=true면 항목별 수정 방법>
|
||||
<breaking=false면 "없음">
|
||||
|
||||
### 배포 시 주의사항
|
||||
<warnings가 있으면 나열>
|
||||
<없으면 섹션 생략>
|
||||
|
||||
### 참고
|
||||
- severity: <severity>
|
||||
- breaking: <true/false>
|
||||
|
||||
---
|
||||
|
||||
Input:
|
||||
<Structured Diff JSON>
|
||||
```
|
||||
|
||||
### 2.3 토큰 예산 관리
|
||||
|
||||
대형 chart(airflow, kafka 등)는 Structured Diff JSON이 매우 클 수 있다.
|
||||
|
||||
| 전략 | 설명 |
|
||||
|------|------|
|
||||
| 중요도 기반 필터링 | breaking_reasons와 changed 항목만 포함, unchanged는 제외 |
|
||||
| template diff 요약 | 리소스별 상세 diff 대신 `변경된 리소스 목록`만 전달 |
|
||||
| 청크 분할 | values / templates / crd를 각각 별도 LLM 호출 후 결과 합산 |
|
||||
| 토큰 상한 설정 | 입력 JSON 최대 크기 제한 (예: 50,000 tokens), 초과 시 요약 버전 사용 |
|
||||
|
||||
### 2.4 출력 검증
|
||||
|
||||
- **금지 규칙**: 입력 JSON에 없는 버전/리소스를 언급하면 실패 처리.
|
||||
- **서식 검증**: Markdown 구조가 규정과 다르면 1회 재생성, 실패 시 fallback 템플릿으로 대체.
|
||||
- **요약 품질 기준**: breaking_reasons 누락/허위 서술은 오류로 간주.
|
||||
|
||||
### 2.5 예상 출력 (breaking=true)
|
||||
|
||||
> `update_docs_file`이 `## {to_version}` 헤더를 추가하므로, LLM 출력은 `###` 수준부터 시작한다.
|
||||
|
||||
```markdown
|
||||
### 변경 요약
|
||||
- from_version: 1.2.3
|
||||
- to_version: 1.3.0
|
||||
- Image tag 1.2.3 → 1.3.0 업데이트
|
||||
- CPU limit 기본값 추가 (all containers)
|
||||
- 새 환경변수 `AIRFLOW__CORE__NEW_SETTING` 추가 (scheduler)
|
||||
|
||||
### custom-values.yaml 수정 필요 항목
|
||||
- **`ingress.enabled` 키 삭제**: 차트에서 해당 key가 제거되었습니다.
|
||||
현재 custom-values.yaml에서 `ingress.enabled: true`로 설정하고 있는 경우,
|
||||
신규 방식(`ingress.create: true` 등)으로 수정이 필요합니다.
|
||||
|
||||
### 배포 시 주의사항
|
||||
- **Service port 변경**: `airflow-webserver` port 8080 → 8081.
|
||||
Ingress, load balancer 설정 확인 필요.
|
||||
|
||||
### 참고
|
||||
- severity: high
|
||||
- breaking: true
|
||||
```
|
||||
|
||||
### 2.6 예상 출력 (breaking=false)
|
||||
|
||||
> 템플릿 기반 fallback 출력 (LLM 미호출).
|
||||
|
||||
```markdown
|
||||
### 변경 요약
|
||||
- from_version: 1.2.3
|
||||
- to_version: 1.3.0
|
||||
- Chart airflow 1.2.3 → 1.3.0 업데이트
|
||||
- Values: +2 추가 / -0 삭제 / ~3 변경
|
||||
- Templates: +0 추가 / -0 삭제
|
||||
|
||||
### custom-values.yaml 수정 필요 항목
|
||||
없음
|
||||
|
||||
### 참고
|
||||
- severity: warning
|
||||
- breaking: false
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Docs Updater 설계
|
||||
|
||||
### 3.1 역할
|
||||
|
||||
생성한 업그레이드 주의사항 Markdown을 해당 차트 버전의 `CUSTOM-README.md`에 반영한다.
|
||||
(`CUSTOM-README.md`는 배포에 관한 내용을 포함하는 문서로, 업그레이드 주의사항의 적합한 위치다.)
|
||||
|
||||
### 3.2 처리 방식
|
||||
|
||||
```
|
||||
1. diff/breaking 결과로 업그레이드 주의사항 생성 (breaking=true면 LLM, 아니면 템플릿)
|
||||
2. manifests/helm/<chart>/<to_version>/CUSTOM-README.md에 반영
|
||||
- "# Upgrade History" 섹션이 없으면 파일 끝에 추가
|
||||
- 해당 버전 항목이 이미 있으면 skip (idempotent)
|
||||
3. 파일 저장
|
||||
```
|
||||
|
||||
### 3.3 파일 구조 규칙
|
||||
|
||||
- 각 차트 버전 디렉토리의 `CUSTOM-README.md`에 업그레이드 주의사항을 추가한다.
|
||||
- `CUSTOM-README.md`는 `chart_updater`가 이전 버전에서 carry-over하므로 기존 배포 내용은 유지된다.
|
||||
- `BUILD-README.md`는 차트 메타 정보(repo, 설치 명령어 등)를 유지한다.
|
||||
- 별도의 `docs/upgrade.md`는 생성하지 않는다.
|
||||
|
||||
### 3.4 중복 방지
|
||||
|
||||
이미 해당 버전 업그레이드 섹션이 존재하면 덮어쓰기 또는 스킵한다 (설정으로 제어).
|
||||
|
||||
---
|
||||
|
||||
## 4. Git PR Bot 설계
|
||||
|
||||
### 4.1 자동화 단계
|
||||
|
||||
```
|
||||
1. 새 branch 생성: update-{chart}/{to_version}
|
||||
2. 카탈로그 신규 버전 디렉토리 커밋 (manifests/helm/<chart>/<to_version>/)
|
||||
3. CUSTOM-README.md 업그레이드 주의사항 섹션 포함
|
||||
4. git commit
|
||||
5. PR 생성
|
||||
```
|
||||
|
||||
### 4.2 PR 메타데이터
|
||||
|
||||
**PR 제목**:
|
||||
```
|
||||
update {chart}: {from_version} → {to_version}
|
||||
```
|
||||
|
||||
**PR labels**:
|
||||
- `needs-review` (breaking=true 시) — 담당자 확인 권장
|
||||
- `auto-update` (breaking=false 시) — 자동 업데이트, 검토 선택적
|
||||
|
||||
**PR description**:
|
||||
```markdown
|
||||
## Helm Chart Update: {chart} `{from_version}` → `{to_version}`
|
||||
|
||||
**Severity**: `high`
|
||||
**Breaking**: ✅ custom-values.yaml 수정 필요 (담당자 확인 권장)
|
||||
|
||||
### Breaking Changes
|
||||
- `[values_key_removed]` ingress.enabled — custom-values.yaml에서 사용 중인 key 삭제
|
||||
|
||||
### Warnings
|
||||
- `[service_port_changed]` Service/airflow-webserver — port 8080 → 8081
|
||||
|
||||
---
|
||||
*Generated by update-catalog automation*
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 관련 문서
|
||||
|
||||
- [02-breaking-change-rules.md](02-breaking-change-rules.md) — Breaking Change 입력 생성
|
||||
- [04-skill-interface.md](04-skill-interface.md) — `generate_upgrade_doc`, `create_pr` Skill
|
||||
Reference in New Issue
Block a user