パッケージは セマンティックバージョニング (SemVer) に従う必要があります。セマンティックバージョニングは、パッケージの作成者が特定のバージョンに含まれている変更のタイプについての情報を提供する手段です。以前のバージョンとの比較情報を自動ツールが使用できる形式で提供できます。
セマンティックバージョニングでは、バージョンを メジャー.マイナー.パッチ という形式で表記します。メジャーは 1 つ以上の破壊的変更を含み、マイナーは 1 つ以上の後方互換性のある API 変更を含み、パッチは API の変更を伴わないバグ修正のみを含みます。
パッケージの開発を開始するときは、バージョン番号を 0.1.0 から始めます。メジャーバージョン番号 0 は、最初の開発段階のパッケージ用に予約されています。初期の開発中、パッケージ API は頻繁に変更され、頻繁に破壊的変更が行われるため、パッケージが十分に安定して本番環境で使用できる状態になるまで、メジャーのバージョン番号を 0 に維持します。
パッケージを正式に本番環境で使えるようなったら、メジャーのバージョン番号を 1 に増加させて、その後の変更については以下のガイドラインに従います。
| 増加する値 | 条件 | 例 |
|---|---|---|
| メジャー | 少なくとも 1 つの破壊的変更が含まれていて、どのバージョンのパッケージも別のバージョンで代替することはできません。破壊的変更には以下が含まれます。 • API サーフェス (API の公開部分) または機能に対する、コンパイルまたはランタイムのエラーリスクを伴う変更。 • API ではない機能の削除 (アセットの削除やアセットの GUID の変更など)。 • アセンブリとアセットの削除または名前変更 (コンパイラーがそれらを検索できない可能性があるため)。 ノート: メジャーバージョンを上げるときには、パッチ と マイナー の値を 0 に必ずリセットしてください。 |
バージョン 1.2.3 と 2.0.0 には互換性がなく、リスクなしで相互に使用することはできません。 |
|
マイナー (同じ メジャー 値) |
最新の マイナー では、後方互換性のある機能を導入します。以下の変更は、API に対する後方互換性のある (破壊的でない) 変更です。 • コンパイルやランタイムのエラーリスクのない API サーフェスや機能の変更。 • API ではない機能の追加。 • アセンブリとアセットの追加 (新しいアイテムには既存の参照がないため)。 ノート: マイナーバージョンを上げるときには、パッチ バージョンを 0 に必ずリセットしてください。 |
バージョン 1.3.0 を使用して 1.2.0 への依存関係を満たすことができます。 1.2.0 を使用して 1.3.0 への依存関係を満たすことはできません。 |
|
パッチ (同じ メジャー.マイナー 値) |
最新の パッチ では、API をまったく変更せずに、後方互換のあるバグ修正を導入します。以下の場合、API は変更されません。 • API サーフェスが同一で、機能が変更されない場合。 • 変更によってパブリック API が変更されない場合。 |
バージョン 1.3.1 に 1.3.0 にはないバグ修正が含まれているとしても、1.3.0 と 1.3.1 には同じ API があるため、相互に使用することができます。 |
これらのバージョニングの方法に従うことで、Package Manager は可能な場合は自動的に競合を解決し、パッケージを新しい後方互換性のあるバージョンにアップグレードします。
以下のセクションでは、これらのルールがさまざまなパッケージ要素にどのように影響するかを判断するのに役立つシナリオを説明します。
通常はマイナーバージョンまたはパッチバージョンの増加のみを必要とする変更であっても、上記のシナリオのほかに、もう 1 つの要素が影響する場合があります。その要素とは Auto Referenced プロパティが有効か無効かということです。
Auto Referenced は アセンブリ定義 に設定できるプロパティの 1 つです。このプロパティでは、コンパイル時に Unity がファイルを自動的に参照するかどうかを制御します。通常はマイナーまたはパッチバージョンの増加のみを必要とする変更であっても、このプロパティを有効にすると、破壊的変更になる場合があります。
自動参照が 無効 である場合は、新しいアセンブリを使用可能にするための変更を加えることによって、API に後方互換性のある変更を適用します。プラットフォームの追加、Unity Test References の無効化、新しい .asmdef の追加、制約定義の削除 など、API に対する後方互換性のある変更には、マイナー バージョン増加のみが必要です。
しかし、自動参照が 有効 である場合は、新たに加わったアセンブリは、他のさまざまなアセンブリの参照に暗示的に追加されます。このような場合は他のアセンブリでコンパイルエラーが生じる可能性があるため、メジャー バージョンの増加が必要になります。
もう 1 つのよくあるケースは、パッケージ依存関係のバージョンを追加または変更した場合に発生します。ほとんどの パッケージ依存関係の変更 の場合は、パッチ のバージョン増加のみが必要です。ただし、Auto Referenced プロパティが 有効 になっているアセンブリを含む新しいパッケージバージョンは破壊的変更になるため、メジャー バージョンの増加が必要です。
このような問題を回避するために、関連のないパッケージにサードパーティの DLL ファイルを置かないようにしてください (例: SaveGameManager パッケージに Newtonsoft.Json.dll を加える)。
プロジェクトは、アセットデータベースに表示されるすべてのアセットを参照できます。アセットデータベースは、.meta ファイルで定義された GUID を使用して、これらのアセットを一意に追跡します。
これらの変更は 破壊的変更 であるため、その 1 つをパブリック API に適用する場合は、新しい メジャー リリースが必要です。
| シナリオ | 破壊的変更である理由 |
|---|---|
| アセットデータベースから見えるアセットの削除 | アセットを削除すると、ユーザーのプロジェクトや他のパッケージの参照を壊す可能性があります。 |
| アセットの GUID の変更 | アセット GUID が変更されると、アセットデータベースはその操作を元のアセットが削除されてから新しい (同一) アセットをが追加されるものと認識します。その結果、参照が切れてしまいます。その理由は、元の GUID がそのアセットを示さなくなるため、アセットデータベースが参照を解決できなくなるからです。 |
アセンブリ定義 (.asmdef) では、Unity エディターのコンパイルパイプラインが個別のマネージアセンブリ (.dll) に変換するスクリプトのグループを定義します。これらの .asmdef アセットには、生成されるされるアセンブリのプロパティを補助するプロパティが含まれます。これには次が含まれます。
ほとんどのプロパティはアセンブリのコンシューマーに影響を与えるため、これらのプロパティを変更すると、パッケージのパブリック API も変更されます。その他のプロパティはアセンブリのコンシューマーに影響を与えないため、変更してもパッケージ API の変更とは見なされません。
注意: Auto Referenced プロパティは例外です。通常では API をまったく変えない変更 や、API に対する後方互換性のある変更 の多くが、Auto Referenced が有効かどうかによって、コンパイルエラーの原因となる可能性があるためです。詳細は、自動参照 を参照してください。
Unity はアセンブリをプリコンパイルすることも、スクリプトとアセンブリ定義からコンパイルすることもできます。したがって、アセンブリ定義に適用されるものは、プリコンパイルされたアセンブリにも大抵適用されます。
ここでは、アセンブリ定義とプリコンパイルされたアセンブリの変更、およびパッケージバージョンへの影響について詳しく説明します。
パブリック API に 破壊的変更 を適用する場合は、コンパイルやランタイムのエラーが発生する可能性があるため、新しい メジャー リリースが必要です。以下のすべてのシナリオでは、他のアセンブリが参照するアゼンブリは、他のアセンブリから削除されるか、非表示になります。参照先アセンブリで定義されたタイプを使用してアセンブリがコンパイルされるときに、コンパイラーが他のアセンブリを検出できないと、コンパイルエラーが発生します。アセンブリとアセンブリ定義の使用についての詳細は、アセンブリ定義 を参照してください。
以下は、パッケージが消費し使用するランタイムアゼンブリとエディターアゼンブリの両方に適用されます。テストアセンブリには適用されません。テストアセンブリは、通常ではパッケージによって消費されないため、パッケージの API の一部ではないからです。
| シナリオ | コンパイラーが参照されるアセンブリを見つけられない理由 |
|---|---|
| アセンブリ定義またはプリコンパイルされたアセンブリの削除 | アセンブリ定義ファイルを削除すると、コンパイルパイプラインが対応するアセンブリを生成しなくなります。 ノート: 2019.1 以降、参照がない場合は “オプションの参照” のユースケースをサポートすることが可能ですが、アセンブリ定義をコンパイルするために必要なアセンブリの名前を変更すると、コンパイルエラーが発生します。同様に、コンパイルされたコードがアセンブリで定義されたタイプを必要とする場合に、そのアセンブリの名前を変更すると、 TypeLoadException などのランタイムエラーが発生することがあります。 |
| アセンブリ名の変更 (.asmdef ファイル内で変更するか、.dll ファイル名を変更) | アセンブリ名を変更することは、アセンブリを削除してから、別の名前で新しいアセンブリを加えることと同じです。つまり、API に同じアセンブリコードが別の名前で含まれていても、Unity は元のアセンブリがないとみなします。 |
| .asmdef への 制約定義 の追加 | 制約定義を追加すると、制約定義が満たされない場合に、アセンブリのコンパイルはスキップされます。これにより、以前は使用可能であったアセンブリが見つからない場合があります。 |
| プラットフォームの削除 | 特定のプラットフォームのサポートを削除すると、Unity はそのプラットフォームのアセンブリをインポートしなくなります。これは、アセンブリを削除することと同じです。 プラットフォームを削除するには、以下のいずれかのプロパティを有効にします。 • includePlatforms: リストに含まれていないすべてのプラットフォームとの互換性が失われます。 • excludePlatforms: プラットフォームにエントリーが追加されます。 |
| パブリック API をあるアセンブリから別のアセンブリに移動 | パブリックアクセスが可能なコードをアセンブリ A からアセンブリ B に移動すると、A を参照し B を参照しないアセンブリはコンパイルされません。 アセンブリ定義に関しては、スクリプトを移動すると、パブリック API を別のアセンブリに移動することになる可能性があります。 |
| Auto Referenced プロパティの変更 |
Auto Referenced プロパティを 無効 にすると、このアセンブリのパブリック API は明示的な参照なしでは使用できなくなります。 • このプロパティを無効にすると、プリコンパイルされたアセンブリは、アセンブリ定義とプロジェクトのコンパイルされたアセンブリへの参照として暗示的に加えられなくなります。 • アセンブリ定義に関しては、このプロパティを無効にすると、生成されるアセンブリがプロジェクトのコンパイルされたアセンブリへの参照として暗示的に追加されなくなります。 Auto Referenced プロパティを 有効 にすると、API、プロパティ、または依存関係への他の変更との競合が発生する可能性があります。詳細は、自動参照 セクションを参照してください。 |
| アセンブリ定義での Unity References → Test Assemblies プロパティの有効化 | Unity References → Test Assemblies プロパティを有効にすると、このアセンブリはテストアセンブリとしてマークされ、通常ではビルドに含まれなくなります (またはコンパイルされないことがあります)。この場合は、欠落したテストアゼンブリを参照するアゼンブリは (それ自体もテストアセンブリである場合を除いて) 欠落したテストアゼンブリを見つけることができません。 |
以下の変更は、API に対する 後方互換性のある 変更または破壊的でない変更です。以下のすべてのシナリオでは、アセンブリを削除する破壊的変更とは違って、アセンブリを追加します。アセンブリの追加は、API サーフェス (API の公開部分) の増加につながるため、API 変更とみなされます。ただし、既存の参照がないため、新しいアセンブリを追加しても、以前の API で作成された他のアセンブリには影響しません。
後方互換性のある変更の場合は、少なくとも新しい マイナー リリースが必要です。破壊的変更を伴う更新は、新しい メジャー リリースに加えることもできます。
注意: これらの変更には、Auto Referenced プロパティが無効の場合にのみ後方互換性があります。Auto Referenced プロパティを有効にすると、この表に示す変更は、破壊的変更になる場合があります。詳細は、自動参照 セクションを参照してください。
| シナリオ | 変更がコンパイルを壊さない理由 |
|---|---|
| .asmdef への 制約定義 の削除 | 制約定義を削除すると、コンパイルとスクリプトのパイプラインはこのアセンブリをスキップしなくなります。Unity は常にそのアセンブリをビルドするので、コンパイラーはその制約定義が満たされているかどうかにかかわらず、常にアセンブリへの参照を解決できます。 |
| プラットフォームの追加 | プラットフォームの追加は、既存のプラットプラットフォームのサポートに影響しないため、後方互換性があります。これは API サーフェスの増加につながるため、API 変更です。 以下のプロパティを変更することで、プラットフォームを追加できます。 • includePlatforms プロパティにエントリーを追加します。 • includePlatforms プロパティを完全に削除します。これは、includePlatforms プロパティに登録されていないすべてのプラットフォームを追加するのと同じことです。 • excludePlatforms プロパティからエントリーを削除します。 |
| 新しいスクリプトでのアセンブリ定義の作成 (別の .asmdef ファイルで既存しない) | 新しいアセンブリを加えると、既存の実装を変更せずに API サーフェス (API の公開部分) を追加します。 |
| アセンブリ定義ファイルでの Unity References → Test Assemblies プロパティの無効化 | Unity References→Test Assemblies プロパティを無効にすると、このアセンブリは通常のアゼンブリとしてマークされるため、他のアセンブリ定義と同様に扱われるようになります。これは API サーフェスの増加につながるため、API 変更です。 |
以下の変更はパブリック API には影響せず、パッチ リリースに入れることができます。これらのシナリオの変更はパブリック API を変更しません。API サーフェス (API の公開部分) に影響せず、他のコンシューマーを何も変更しないからです。
パブリック API に影響しない変更の場合は、少なくとも新しい パッチ リリースが必要です。破壊的変更、または破壊的でない変更を適用するその他の更新は、メジャー または マイナー リリースに加えることもできます。
| シナリオ | 変更が他のコンシューマーに影響しない理由 |
|---|---|
| .asmdef ファイルでの参照アセンブリとアセンブリ定義のリスト変更 | 別のアセンブリを参照するアセンブリは、他のアセンブリの参照先を自動的に参照するわけではなく、参照先の明示的な列挙が必要です。したがって、アセンブリ定義やアセンブリで参照を変更しても、他のコンシューマーには影響しません。 |
| アセンブリ定義の Allow unsafe code プロパティの変更 | このプロパティでは、コンパイラーが unsafe モディファイアを持つコードをコンパイルできるかどうかを制御します。このフラグ自体を変更しても、パブリック API は変更されません。 |
| アセンブリ定義の Override References プロパティの変更 | このプロパティでは、Unity がこのアセンブリのコンパイラーを呼び出す方法を制御します。生成されるアセンブリのコンシューマーへの影響はありません。このフラグ自体を変更しても、パブリック API は変更されません。 |
パッケージマニフェスト ファイル (package.json) では、パッケージ自体の名前、バージョン、パッケージ依存関係、その他のメタデータを指定します。
ここでは、パッケージマニフェストファイルの変更、およびパッケージバージョンへの影響について詳しく説明します。
name プロパティを変更することは、あるパッケージを削除して、別名で新しいパッケージを加えることと同じであり、サポートされていません。更新をリリースするためにパッケージの名前を変更することはできません。まったく新しいパッケージとしてリリースする必要があります。既存のプロジェクトとパッケージは名前を同義語として解釈できないため、名前の変更はできません。
プロジェクト内の依存関係を変更するのに、メジャーまたはマイナーの別バージョンは必要ありません。ただし、その変更が API 変更の一部である場合、または Auto Referenced プロパティが有効である場合は例外です。
このセクションでは、依存関係の変更の例と、それらが適用されるコンテキストを説明します (Auto Referenced プロパティが無効で、各ケースの説明の他には API の変更がないと仮定します)。
| 依存関係の変更 | コンテキスト | 最小限のバージョン変更 |
|---|---|---|
| 新しい依存関係の追加 | • 新しいパッケージを使用し、機能動作を変更しない。API サーフェスを変更しない。 | パッチ |
| • 新しいパッケージを使用し、新しい動作を導入する。API サーフェスを変更しない。 • 新しいパッケージで定義されたタイプを公開する新しい API を作成する。 |
マイナー | |
| • 新しいパッケージを使用し、既存の動作に対して後方互換性のない変更を適用する。API サーフェスを変更しない。 • 新しいパッケージで定義されたタイプを公開するために、既存の API に対して後方互換性のない変更を適用する。 |
メジャー | |
| 依存関係の削除 | • 機能動作を変更せずにパッケージを削除する。API サーフェスを変更しない。 | パッチ |
| • パッケージを削除すると、既存の動作に後方互換性のない変更が適用される。API サーフェスを変更しない。 • その依存関係で定義されたタイプを公開するための API を削除する。 |
メジャー | |
| 依存関係の変更 | • 変更されたパッケージを使用し、機能動作を変更しない。API サーフェスを変更しない。 | パッチ |
| • 変更されたパッケージを使用し、新しい動作を導入する。API サーフェスを変更しない。 • 変更されたパッケージで定義されたタイプを公開するための新しい API を作成する。 |
マイナー | |
| • 変更されたパッケージを使用し、既存の動作に対して後方互換性のない変更を適用する。API サーフェスを変更しない。 • 変更されたパッケージで定義されたタイプを公開するために、既存の API に対して後方互換性のない変更を適用する。 • 変更されたパッケージで後方互換性のある変更が適用された API でいくつかのタイプを公開する。 • 変更されたパッケージで定義されなくなった API でいくつかのタイプを公開する。 |
メジャー |
どのリリースバージョンでも、Package Manager、ビルドパイプライン、スクリプティングパイプライン、またはアセットデータベースに特別な影響を与えないパッケージマニフェスト属性を変更できます。これには、description、category、keywords、displayName の変更が含まれます。
これらのフィールドを変更するということは、単なるバグ修正に留まらない可能性があります。新しいバージョンに含まれる他の変更のために、パッチリリースではなくマイナーまたはメジャーリリースが必要となるかどうかを必ず検討してください。
ノート: パッケージマニフェストの unity または unityRelease プロパティを変更する場合は、必ずマイナーまたはメジャーリリースが必要です。これらのプロパティはパッケージの API 自体には影響しませんが、Unity のバージョンを上げると、パッケージのバージョンが以前の Unity エディターで動作しなくなり、依存するプロジェクトやパッケージが壊れる可能性があります。Unity バージョンを下げると、古い Unity エディターでパッケージを使用できるようになります。
API から一部の機能を削除する場合は、非推奨を含むマイナーバージョンを少なくとも 1 つリリースします。これにより、廃止が差し迫っていることをユーザーに警告し、新しい API にスムーズに移行できるようにします。その後、新しいメジャーリリースで機能を削除できます。
パッケージに廃止の警告が付けられている場合に、プロジェクトで Warnings as Errors を有効にすると、コードは以前と同じように機能します。以前のように機能するため実際には本当に壊れていなくても、古いパッケージは技術的にプロジェクトを壊す可能性があります。
この場合、エラーの警告をどのように修正するかを選択できます (通常望ましい方法を上から順に)。
#pragma warning ディレクティブで API を使用するコードをラップして、警告を止めます。