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 後方互換性保証

マイナーバージョン更新時の後方互換性保証：

既存の必須フィールドを削除しない
新規フィールドはデフォルトでオプション
既存フィールドのセマンティクスを変更しない
列挙型の値域を狭めない
既存インターフェースの必須パラメータを増やさない