重大な変更

MRTK のコンシューマーは、安定したリリースからリリースまでの API サーフェスがあるかどうかによって異なります。そのため、毎回重大な変更を加えることなく、MRTK の更新を行うことができます。

このページでは、MRTK での重大な変更に関する現在のポリシーについて説明します。さらに、互換性に影響する変更を抑え、コードに対して正しい長期的な技術的な変更を行うためのトレードオフの管理方法について、長期的な目標をいくつか示します。

互換性に影響する変更点

リスト aのいずれかの条件を満たし、リスト Bのすべての条件を満たす場合、変更は重大な変更になります。

一覧を表示する

  • 任意のインターフェイスのメンバーまたは関数の追加、削除、または更新 (または、インターフェイス全体の削除または名前の変更)。
  • 保護されているメンバーまたはパブリックメンバーまたはクラスの関数の削除、更新 (型/定義の変更、プライベートまたは内部の作成)。 (またはクラス全体の削除または名前の変更)。
  • クラスによって発生したイベントの順序の変更。
  • ScriptableObject (特にプロファイルに対する変更) のプライベート SerializedField (対応する FormerlySerializedAs タグなし) またはパブリックプロパティの名前変更。
  • ScriptableObject のフィールドの種類 (特にプロファイルに対する変更) を変更する。
  • 任意のクラスまたはインターフェイスの名前空間または asmdefs を更新します。
  • Prefab の最上位レベルのオブジェクトでのスクリプトの削除または削除。

リスト B

  • 問題の対象となる資産は、foundation パッケージに含まれています (つまり、次のいずれかのフォルダーにあります)。

    • MRTK/コア
    • MRTK/Providers/
    • MRTK/Services/
    • MRTK/SDK/
    • MRTK/Extensions
  • 問題の資産は試験的な名前空間に属していません。

重要

例のパッケージに含まれている資産 (MRTK/例/フォルダーの一部) はいつでも変更される可能性があります。これは、コンシューマーが ' 参照の実装 ' としてコピーおよび表示するように設計されている資産であり、Api と資産のコアセットの一部ではないためです。 試験的な名前空間 (または一般に試験段階としてラベル付けされた機能) の資産は、すべての期限が切れた後に発行される資産 (つまり、テスト、UX イテレーション、ドキュメント) であり、すぐにフィードバックを得るために発行されます。 ただし、これらにはテストとドキュメントが含まれていないため、すべての相互作用と設計を明確していない可能性があるため、パブリックでは、それらが変更されたり変更されたりする (変更、完全に削除される) ことを前提とする状態で公開します。

詳細については、試験的な 機能 を参照してください。

重大な変更のためのセキュリティ面は非常に大きいため、重要なのは、"互換性に影響する変更はありません" という絶対的なルールを持つことができないということです。これは、重大な変更を加えることによって、sane でしか修正できない問題がある可能性があることに注意してください。 別の方法として、"重大な変更はありません" という唯一の方法は、まったく変更されないことです。

継続的なポリシーは、可能な場合には重大な変更を回避することであり、変更によって重要な顧客またはフレームワークの長期的な値が発生する場合にのみ実行します。

互換性に影響する変更点

互換性に影響する変更を加えることなく、機能の長期的な構造と実行可能性を損なうことなく、何らかの処理を行うことができる場合は、互換性に影響する変更を行いません。 それ以外の方法がない場合、現在のポリシーでは、個々の重大な変更を評価し、変更を行うことによるメリットが、変更を吸収する際のコストよりも大きいかどうかを把握します。 重要なことと、PR または問題の説明については、一般的に行われないことについて議論します。

ここでは、いくつかのバケットに分類されることがあります。

互換性に影響する変更によって値が追加されますが、中断されない方法で記述できます。

たとえば、 この PR には、中断された方法で最初に記述された新しい機能が追加されました。既存のインターフェイスは変更されていますが、その機能が独自のインターフェイスとして分割された場所で書き直されました。 これは、一般に最適な結果です。 互換性のない形式に変更を加えることは、長期的な可能性や機能の構造を損なう可能性がある場合には避けてください。

重大な変更により、顧客にとって価値のある価値が追加されます。

互換性に影響する変更点を文書化し、最適な軽減策を提供します (つまり、移行方法や、お客様に自動的に移行されるツールをより適切に移行するための規範的な手順)。 各リリースには、一部の変更が含まれている可能性があります。 この PRで行ったように、ドキュメントには常に記載されています。 既に 2.x +1 + 1 の移行ガイドがある場合は、そのドキュメントに命令またはツールを追加します。存在しない場合は、作成します。

重大な変更によって値が追加されますが、顧客の問題が大きくなりすぎます

すべての種類の重大な変更が同じように作成されるわけではありません。経験やカスタマーエクスペリエンスに基づいて、他のすべての種類の変更が非常に困難になります。 たとえば、インターフェイスへの変更は困難な場合がありますが、重大な変更とは、過去に拡張または実装されている可能性が低い (診断視覚化システムなどの) ことが考えられます。 ただし、変更が ScriptableObject のフィールドの種類 (たとえば、MRTK のコアプロファイルのいずれか) である場合は、顧客に大きな問題が発生する可能性があります。 お客様は既に既定のプロファイルを複製しています。また、プロファイルのマージ/更新は、(マージ時にテキストエディターを使用して) 手動で行うのが非常に困難です。また、既定のプロファイルを再構成して、すべてを手動で再構成すると、回帰のデバッグが困難になる可能性があります。

これらの変更は、重大な変更を可能にする分岐が存在するまで (顧客がアップグレードの理由を提供する重要な価値とともに)、シェルフに戻す必要があります。 このような分岐は現在存在しません。 今後のイテレーション計画ミーティングでは、変更/問題が重大なものになったかどうかを確認して、一連の変更を一度に実行するのが妥当であるかどうかを確認します。 エンジニアリングリソースが限られているため、"すべての処理が許可されました" というブランチを作成することは危険であることに注意してください。また、テストと検証を分割する必要があります。 このようなブランチが存在する場合は、明確な目的と、そのブランチの開始日と終了日を明確にする必要があります。

互換性に影響する変更の長期的な管理

長期的には、 リスト Bで条件のセットを増やすことによって、互換性に影響する変更の範囲を減らすことをお勧めします。 リスト A で一連の項目を進めると、"パブリック API サーフェイス" に含まれるファイルとアセットのセットについて、常に技術的に問題になります。 反復処理をより自由にする方法 (つまり、内部実装の詳細を変更し、複数のクラス間でコードを簡単にリファクタリングできるようにするなど) は、実装の詳細ではなく、コードのどの部分が正式なサーフェイスであるかをより明確にすることです。

すでに実行したことの1つは、"試験的な" 機能の概念を紹介することです (試験的な名前空間に属しており、テスト/ドキュメントが含まれておらず、既に存在していても、警告なしで削除および更新される可能性があります)。 これにより、以前のフィードバックを取得するために新しい機能をすぐに追加できるようになりましたが、api サーフェイスにすぐに関連することはできません (API サーフェスを完全に考えることができない場合があるため)。

将来に役立つ可能性のあるその他の例

  • 内部キーワードの使用。 これにより、外部のコンシューマーに公開することなく、独自のアセンブリ内でコードを共有できるようになります (コードの重複を減らすことができます)。
  • "Internal" 名前空間の作成 (例: Toolkit MixedReality)。内部のユーティリティ)。内部名前空間に含まれるものはいつでも変更され、削除されることがあります。これは、C++ ヘッダーライブラリが:: internal 名前空間を使用して実装の詳細を非表示にする方法と似ています。