互換性:リリースが約束すること
Aggrega をアップグレードすると、利用者が依拠している複数の対象が変わる可能性があります。ドキュメントの記述の基になるスキーマ、スクリプトが呼び出すコマンドとフラグ、AI アシスタントが呼び出すツール、記録しているエラーコード、そしてプラグインのビルドに使うプラグインキットです。このページでは、それぞれについて、リリースが何を変更してよく、何を変更しないかを示します。このページで取り上げていない対象には、その対象自身のリファレンスページに記載されている内容を超える約束はありません。最後のセクションでは、いずれかが変更されたことをリリースがどこで知らせるかを説明します。このページの約束は 0.9.0 から適用されます。0.9.0 より前の Releases はサポート対象外です。ハブレジストリである hub.aggrega.ai は、それらに向けて作られた Plugin のバージョンを一切提供しておらず、それらのコンパイラは、ドキュメントが aggrega.ai/v1beta1 を宣言しているこのレジストリのカタログを読み取れません。
Aggrega は 0.x.y 形式のバージョンでリリースされます。パッチリリースは最後の数字を、マイナーリリースは中央の数字を上げます。カタログエンティティ自身の metadata.version は別の問題です——その作成者が、aggrega lint --pre-publish がチェックするバージョン引き上げの基準に従って選択します。参照がそのうち 1 つをどのように選択するかは バージョン解決 で説明しています。
スキーマ
Aggrega が公開するすべてのスキーマは、1 つの API バージョン aggrega.ai/v1beta1 に属します——これはエンティティドキュメントが apiVersion で宣言する値です。以下のルールはそのそれぞれに適用されます:エンティティの種類、プラグインのペイロード、そしてワークスペースやその他のスキーマ——IR、ワークスペース設定、ロックファイルなど——で、いずれも スキーマリファレンス に一覧があります。API バージョンはリリース番号とは別のものであり、多くのリリースが同じ API バージョンを読み取ります。
v1beta1 の範囲内で変更されうること
1 つの API バージョンの範囲内では、Kubernetes が自身の API バージョンを変更するのと同様に、スキーマは追加的にのみ変更されます。リリースでは次のことが行われる場合があります:
- 説明を変更すること。
- フィールドを追加すること(そのフィールドが省略可能である場合)。
このような変更の前に有効だったすべてのドキュメントは、変更後も有効であり、同じ意味を持ちます。コンパイラが書き出すドキュメント(IR やロックファイルなど)を読み取るプログラムは、未知のフィールドを受け入れる必要があります。v1beta1 の範囲内では、追加された省略可能なフィールドがその出力に現れる可能性があるためです。
v1beta2 が必要になること
以下の変更にはそれぞれ、新しい API バージョン aggrega.ai/v1beta2 が必要です:
- フィールドを削除する、または名前を変更すること。
- フィールドを必須にすること。
- 型、またはフィールドが受け付ける値の集合を狭めること。
- 値の意味を変えること。
新しい API バージョンは破壊的変更であり、それを導入するリリースで破壊的変更として予定され、告知されます。
新しい省略可能なフィールドは、それを認識するコンパイラとともにカタログに届く
コンパイラは、スキーマが宣言していないフィールドを拒否します。この厳格さこそがキーの綴り間違いを検出するものですが、そこには読者が予想しないであろう帰結が 1 つあります:カタログエンティティが新たに追加された省略可能なフィールドを使い始められるのは、そのフィールドを認識するコンパイラを同梱したリリースにおいてのみです。
たとえば、あるリリースが Component のスキーマに省略可能なフィールドを追加するとします——仮に spec.newField と呼びます:
- そのリリースより前に書かれたすべての Component は引き続き有効です。いずれもそのフィールドを設定していません。
- カタログ作成者が、
spec.newFieldを設定する Component の新しいバージョンを公開します。 - そのリリース、またはそれ以降のリリースのコンパイラは、その Component を検証してビルドします。
- それより前のリリースのコンパイラは、自身のスキーマがそのフィールドを宣言していないため、これを拒否します。検証では
spec.newField: unexpected propertyが報告され、該当行が示されます。
したがって、そのカタログバージョンを対象にビルドする人は、まずそのフィールドを追加したリリースにアップグレードし、カタログはそのリリースが公開された後にのみ、そのフィールドを使うエンティティを公開します。ロックされた Release が解決済みのバージョンをどのように保持するかは、バージョン解決 に記載されています。
コマンドラインとアシスタントツール
スクリプト、CI パイプライン、アシスタントの設定は、aggrega のコマンド、フラグ、アシスタントツールを名前で呼び出します。0.x リリースでは次のとおりです:
- パッチリリースで、コマンド、フラグ、アシスタントツールが削除されたり名前が変更されたりすることはありません。
- マイナーリリースではそれらのいずれかを削除または名前変更する場合があり、その変更履歴の Removed または Changed に記載されます。
- 追加——新しいコマンド、フラグ、ツール——は、どのリリースにも含まれる可能性があります。
アシスタントツールとは、aggrega mcp が接続されたアシスタントに提供するツールです。その完全な一覧はサーバー自身の応答であり、それを要求する方法は アシスタントが Aggrega でできること で説明しています。コマンドを実行するツールは、そのコマンドの呼び出しパスから名前を取るため、コマンドの名前を変更するとそのツールの名前も変わります。CLI の概要 にすべてのコマンドが記載されています。
エラーコード
停止を伴うすべての条件には短いコード——文字 E と 4 桁の数字、たとえば [DEVELOPER_ERROR E0007]——が付いており、診断の先頭に出力されます。短いコードは公開された契約です:コードは一度だけ割り当てられ、番号が振り直されることはなく、別の条件に割り当てられることもありません。 廃止された条件のコードは廃止されたままであるため、ランブック、CI ルール、issue に記録されたコードは、どのアップグレードの後でも同じ条件を指します。
エラーセンチネル では、条件が持つ識別子——人が引用する短いコード、プログラムが記録する説明的なコード、プログラムが照合に使う Go のアクセサー——について、それぞれが何を約束するか、また廃止された番号が再び割り当てられないようにする方法を説明しています。その 全条件の一覧表 は廃止されたものも含めてすべての短いコードを解決し、aggrega explain はターミナルで 1 つのコードを解決します。
Plugin キット
プラグイン開発キット——github.com/aggrega-ai/aggrega-pdk/go、aggrega-pdk-rust、@aggrega-ai/aggrega-pdk-typescript——と、それらが再エクスポートする aggrega-abi コーデックは、0.9.0 からセマンティックバージョニングに従います。3 言語のキットは 1 つのバージョン番号を共有し、3 言語のコーデックは別のバージョン番号を共有します。
- あるバージョンを対象にビルドしたプラグインは、同じ系列の以降のすべてのリリースを対象にしても引き続きビルドできます。
0.9.xの範囲内では、リリースはエクスポートされた関数、型、定数を追加することがありますが、それらを削除または変更することはありません。 - エクスポートされた API への破壊的変更は、新しいマイナーバージョンでのみ提供されます(
0.9.xから0.10.0)。パッチリリースが互換性を壊すことはありません。キットとコーデックは Aggrega 自身の1.0.0と同時に1.0.0へ移行し、それ以降は破壊的変更によってメジャー番号が上がります。 - コーデックの破壊的変更はキットの破壊的変更でもあり、キットはそれに合わせて自身のマイナーバージョンを上げます。キットがコーデックの型を再エクスポートしているためです。
- 既存の型に追加されたフィールドやメンバーが追加として扱われるかどうかは、言語によって異なります。パッケージとともに公開される各キットの README には、その言語の場合が「Compatibility」の項に記載されています。
この約束は、プラグインのソースが参照する API を対象とします。コンパイラと実行中のプラグインの間でやり取りされるものは、代わりにプラグイン ABI バージョンによって保たれます:1 つの ABI バージョンの範囲内では、ソケットに追加されるのは説明と省略可能なフィールドのみであるため、それを対象にビルドしたプラグインは引き続き読み込まれます。プラグイン契約 はソケットについて、プラグイン開発者ガイド はそれらを取り巻くワークフローについて説明しています。
リリースの変更履歴に記載される内容
各リリースのノートは リリースページ にあり、Added、Changed、Removed、Fixed などの見出しの下にまとめられた変更履歴を含みます。このページで扱う対象については次のとおりです:
- 削除または名前変更されたコマンド、フラグ、アシスタントツールは、その変更を行うマイナーリリースで Removed または Changed の下に記載されます。
- 新しいスキーマ API バージョンは、それを導入するリリースで破壊的変更として告知されます。
- プラグインキットまたはコーデックの破壊的変更は、そのバージョン番号に表れます:
1.0.0未満の新しいマイナーバージョンになります。 - エラーコードの意味が変わることはないため、告知すべきものを持つリリースはありません。