パッケージは セマンティックバージョニング (SemVer) に従う必要があります。セマンティックバージョニングは、以前のバージョンと比較して、加えられた変更のタイプに関する情報を提供するための方法です。セマンティックバージョニングの形式では、自動化されたツールが使用できます。
セマンティックバージョニングはバージョンを MAJOR.MINOR.PATCH の形式で表現します。MAJOR (メジャー) は 1 つ以上の破壊的変更を含み、MINOR (マイナー) は 1 つ以上の後方互換性のある API 変更を含み、PATCH (パッチ) は API の変更を伴わないバグ修正のみを含みます。
パッケージの開発を開始するときは、バージョン番号を 0.1.0 から始めます。メジャーバージョン番号 0 は、最初の開発段階のパッケージ用に予約されています。初期の開発中、パッケージ API は頻繁に変更され、頻繁に破壊的変更が行われるため、パッケージが十分に安定して本番環境で使用できる状態になるまで、メジャーのバージョン番号を 0 に維持します。
パッケージを正式に本番環境で使えるようなったら、メジャーのバージョンを 1 に増やし、その後の変更については以下のガイドラインに従います。
| 増加する値 | 条件 | 例 |
|---|---|---|
| MAJOR (メジャー) | 少なくとも 1 つの破壊的変更があり、このパッケージのどのバージョンも他のもので代用することができません。破壊的変更には以下が含まれます。 • コンパイルの問題やランタイムエラーの原因となる API サーフェス (API の公開部分) または機能の変更。 • アセットの削除やアセットの GUID の変更など、API 以外の機能の削除。 • アセンブリとアセットの削除や名前の変更 (コンパイラーがそれらを見つけるのに失敗する可能性があるため)。 ノート: メジャーバージョンの値を増加するときは、必ず PATCH と MINOR の値を 0 にリセットしてください。 |
バージョン 1.2.3 と 2.0.0 には互換性がなく、リスクなしで相互に使用することはできません。 |
|
MINOR (マイナー) (同じ MAJOR 値) |
より新しいバージョンの MINOR では、後方互換のある機能を導入します。後方互換性のある (破壊的でない) API 変更には、以下が含まれます。 • コンパイルの問題やランタイムエラーの原因とならない API サーフェス、または機能の変更。 • API 以外の機能の追加。 • アセンブリとアセットの追加 (新しいアイテムには既存の参照がないため) ノート:マイナーバージョンを増加するときは、必ず PATCH の値を 0 にリセットしてください。 |
バージョン 1.3.0 を使用して 1.2.0 への依存関係を満たすことができます。なぜなら、1.3.0 に後方互換性があるためです。 1.2.0 を使用して 1.3.0 の依存関係を満たすことはできません。 |
|
PATCH (パッチ) (同じ MAJOR.MINOR 値) |
より新しいバージョンの PATCH では、API をまったく変更せずに、後方互換を保ったままバグを修正します。以下の場合、API は変更されません。 • API サーフェスが同一で、機能が変更されない場合。 • 変更によってパブリック API が変更ない場合。 |
バージョン 1.3.1 に 1.3.0 にはないバグ修正が含まれているとしても、1.3.0 と 1.3.1 には同じ API があるため、相互に使用することができます。 |
これらのバージョニングの方法に従うことで、Package Manager は可能な場合は自動的に競合を解決し、パッケージを新しい後方互換性のあるバージョンにアップグレードします。
以下のセクションでは、これらのルールがさまざまなパッケージ要素にどのように影響するかを判断するのに役立つシナリオを説明します。
これらのシナリオに加えて、通常はマイナーかパッチバージョンの増加のみを必要とする変更に影響を与えるもう 1 つの要因があります。それは、Auto Referenced プロパティが有効か無効かです。
アセンブリ定義に設定できるプロパティの 1 つに Auto Referenced (自動参照) プロパティがあります。これは、コンパイル中に Unity が自動的にファイルを参照するかどうかを制御します。このプロパティを有効にすると、通常はマイナーまたはパッチバージョンの増加のみを必要とする一部の変更が、破壊的変更になります。
自動参照を無効にすると、新しいアセンブリを使用可能にする変更を行う場合は、API に後方互換性のある変更が加えられます。プラットフォームの追加、Unity Test References の無効化、新しい .asmdef の追加、制約定義の削除など、後方互換性のある API の変更は、MINOR 値の増加のみが必要です。
しかし、自動参照を有効にすると、新しく追加されたアセンブリは、他のさまざまなアセンブリの参照に暗示的に加えられます。このようなケースが他のアセンブリでコンパイルエラーの原因となる可能性があるため、MAJOR 値を増加する必要があります。
別のよくあるケースは、パッケージの依存関係のためにバージョンを加えるまたは変更するときに発生します。ほとんどの場合、パッケージの依存関係を変更するには PATCH を増やすだけです。ただし、新しいパッケージバージョンには、 Auto Referenced プロパティが有効であるアセンブリが含まれている場合があります。これは破壊的変更になるため、MAJOR の増加が必要です。
このような問題を回避するために、サードパーティの 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 を無効にすると、このアセンブリのパブリック API を明示的に参照しないと使用できなくなります。 • プリコンパイルされたアセンブリの場合、このプロパティを無効にすると、プリコンパイルされたアセンブリを、アセンブリ定義への参照やプロジェクトのコンパイルしたアセンブリへの参照として暗示的に加えられなくなります。 • アセンブリ定義の場合、このプロパティを無効にすると、生成されたアセンブリをプロジェクトのコンパイルしたアセンブリへの参照として暗示的に加えられなくなります。 Auto Referenced プロパティを有効にすると、API、プロパティ、依存関係に対する他の変更との競合が発生する可能性があります。詳細は自動参照を参照してください。 |
| アセンブリ定義で Unity References → Test Assemblies プロパティを有効にする | Unity References → Test Assemblies プロパティを有効にすると、このアセンブリをテストアセンブリとして認識させます。そして、Unity は通常、それをビルドに加えません (場合によっては、コンパイルしません)。これが発生すると、欠落しているアセンブリを参照しているアセンブリは、(自体がテストアセンブリでない限り) 欠落しているアセンブリを見つけることができません。 |
以下の変更は、後方互換性のある 、または破壊的でない 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 プロパティを無効にすると、このアセンブリは通常のアセンブリとして認識され、Unity は他のアセンブリ定義と異なる扱いをしなくなります。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 の型を公開します。 |
メジャー |
任意のリリースバージョンのパッケージマネージャー、 ビルドパイプライン、スクリプティングパイプライン、アセットデータベースに特別な影響を与えないパッケージマニフェスト属性を変更できます。これには、description、category、keyword、displayName の変更が含まれます。
これらのフィールドを変更するということは、それは単なるバグの修正ではないかもしれません。新しいバージョンの他の変更によって、実際にパッチリリースではなく、マイナーリリースかメジャーリリースになる可能性を常に考慮してください。
ノート: パッケージマニフェストの unity または unityRelease プロパティの変更には、必ず MINOR または MAJOR のいずれかのリリースが必要です。このプロパティはパッケージの API 自体には影響しませんが、Unity のバージョンを上げると、パッケージのバージョンが以前の Unity エディターで動作しなくなり、依存するプロジェクトやパッケージが壊れる可能性があります。
API から一部の機能を削除する場合は、まず、廃止機能を含むマイナーバージョンを少なくとも 1 つリリースします。これにより、廃止が差し迫っていることをユーザーに警告し、新しい API にスムーズに移行できるようにします。その後、新しいメジャーリリースで機能を排除できます。
パッケージに廃止の警告が付けられている場合に、プロジェクトで Warnings as Errors (エラーの警告) を有効にすると、コードは以前と同じように機能します。以前のように機能するため実際には本当に壊れていなくても、古いパッケージは技術的にプロジェクトを壊す可能性があります。
この場合、エラーの警告をどのように修正するかを選択できます (通常望ましい方法を上から順に)。
#pragma warning ディレクティブで API を使用するコードをラップして、警告を止めます。