BLUEPRINT

제8장: 버전 관리

8.1 개요

프로토콜 버전 관리는 프로토콜 진화 과정에서 호환성을 보장하여, 스킬 제공자와 소비자가 새 버전으로 원활하게 전환할 수 있도록 합니다.

8.2 시맨틱 버저닝

프로토콜은 Semantic Versioning(시맨틱 버저닝) 사양을 따릅니다:

MAJOR.MINOR.PATCH

버전 번호	변경 유형	호환성
MAJOR	호환되지 않는 프로토콜 변경	파괴적 변경. 소비자 업그레이드 필요
MINOR	하위 호환되는 기능 추가	이전 버전 소비자가 정상 작동 유지
PATCH	하위 호환되는 문제 수정	문서 수정, Schema 수정

8.3 버전 선언

모든 Skill Descriptor는 준수하는 프로토콜 버전을 선언해야 합니다:

{
  "protocol": {
    "version": "1.0.0",
    "changelog_url": "https://skill-sharing.org/changelog"
  }
}

8.4 버전 호환성 규칙

호환성 판정

소비자 지원 버전: X.Y.Z
Descriptor 프로토콜 버전: A.B.C

호환 조건: A == X (메이저 버전 동일)
비호환 조건: A != X (메이저 버전 상이)

호환성 매트릭스 예시

소비자 버전	Descriptor 버전	호환성	설명
1.0.0	1.0.0	✓ 호환	정확히 일치
1.0.0	1.2.0	✓ 호환	마이너 버전은 하위 호환
1.0.0	1.2.3	✓ 호환	패치 버전은 하위 호환
1.0.0	2.0.0	✗ 비호환	메이저 버전 상이
2.0.0	1.5.0	✗ 비호환	메이저 버전 상이

버전 비호환 응답

소비자가 비호환 프로토콜 버전을 만난 경우:

{
  "error": {
    "code": "VERSION_INCOMPATIBLE",
    "message": "Protocol version 2.0.0 is not compatible with consumer version 1.x",
    "details": {
      "descriptor_version": "2.0.0",
      "consumer_supported_range": "1.x.x",
      "upgrade_url": "https://skill-sharing.org/upgrade-guide"
    }
  }
}

8.5 Schema 버전화 디렉토리

Schema 정의 파일은 버전별로 구성됩니다:

schema/
├── draft/                    # 현재 개발 중인 초안
│   ├── schema.json
│   ├── schema.ts
│   └── schema.mdx
└── 2025-10-25/              # 게시된 버전
    ├── schema.json
    ├── schema.ts
    └── schema.mdx

draft/: 현재 개발 중인 최신 버전. 불안정한 변경을 포함할 수 있음
{date}/: 게시된 안정 버전. 릴리스 날짜로 명명

8.6 버전 변경 로그

프로토콜 Schema에는 버전 변경 로그에 대한 참조 경로(changelog_url)가 포함되어 각 버전의 변경 내용을 기록합니다:

새로 추가된 필드 또는 기능
더 이상 사용되지 않는 필드 또는 기능
파괴적 변경 설명
마이그레이션 가이드

8.7 하위 호환성 보장

마이너 버전 업데이트 시 하위 호환성 보장:

기존 필수 필드를 삭제하지 않음
새 필드는 기본적으로 선택사항
기존 필드의 의미를 변경하지 않음
열거형 타입의 값 범위를 축소하지 않음
기존 인터페이스의 필수 파라미터를 추가하지 않음