試験的な機能 — MRTK2
MRTK チームが取り組んでいる機能の中には、完全には詳細が具体化されていなくても、多数の初期値が含まれているように見えるものがあります。 この種の機能は、コミュニティで早期に確認していただきたいと考えているものです。 これらはサイクルの初期段階にあるため、Experimental とラベル付けすることにより、今後も進化し、時間の経過と共に変更される可能性がある機能であることを示しています。
実験的な機能に想定されること
コンポーネントが Experimental とマークされている場合は、次のことが想定されます。
- 使用方法を示すシーンの例が
MRTK/Examples/Experimentalサブフォルダーの下にあります - 実験的な機能にはドキュメントが含まれていない可能性があります。
- 多くの場合、テストは含まれていません。
- 実験的な機能は変更される可能性があります。
実験的な機能のガイドライン
実験的なコードは独立したフォルダーに配置する必要がある
実験的なコードは、上位レベルの Experimental フォルダーの下にある実験的機能名を付けたフォルダーに配置します。 たとえば、新機能 FooBar を投稿する場合は、コードを次のように配置します。
- サンプルのシーンやスクリプトは、
MRTK/Examples/Experimental/FooBar/に配置します - コンポーネント スクリプトやプレハブは、
MRTK/SDK/Experimental/FooBar/に配置します - コンポーネント インスペクターは、
MRTK/SDK/Inspectors/Experimental/FooBarに配置します
実験的機能名の下にサブフォルダーを使用する場合は、MRTK と同じフォルダー構造をミラーリングします。
たとえば、ソルバーは MRTK/SDK/Experimental/FooBar/Features/Utilities/Solvers/FooBarSolver.cs に配置します
シーンは、上位の近くにあるシーン フォルダーに保持します: MRTK/Examples/Experimental/FooBar/Scenes/FooBarExample.unity
Note
単一の Experimental ルート フォルダーを使用するのではなく、代わりに MRTK/Examples/HandTracking/Scenes/Experimental/HandBasedMenuExample.unity などように、ルートの下に Experimental を配置することを検討しました。 実験的な機能が見つけやすくなるように、ベースにあるフォルダーを使用することにしました。
実験的なコードは特別な名前空間に配置する必要がある
実験的なコードは、必ず、非実験的な場所に対応する実験的な名前空間に配置するようにします。 たとえば、コンポーネントが Microsoft.MixedReality.Toolkit.Utilities.Solvers にあるソルバーの一部である場合、その名前空間は Microsoft.MixedReality.Toolkit.Experimental.Utilities.Solvers である必要があります。
例については、こちらの PR を参照してください。
実験的な機能には [Experimental] 属性が必要である
いずれかのフィールドの上に [Experimental] 属性を追加して、コンポーネント エディターに、この機能が実験的なものであり、大幅な変更の対象となることを示す小さなダイアログが表示されるようにします。
実験的な機能のメニューは "Experimental" サブメニューに表示する
エディターでメニューにコマンドを追加する際は、実験的な機能は必ず "Experimental" サブメニューの下に表示されるようにします。 次に例をいくつか示します。
トップレベル メニューのコマンドの追加:
[MenuItem("Mixed Reality Toolkit/Experimental/MyCommand")]
public static void MyCommand()
コンポーネント メニューの追加:
[AddComponentMenu("MRTK/Experimental/MyCommand")]
ドキュメント
実験的な機能に関するドキュメントを追加するには、次の手順に従います。
実験的な機能に関するドキュメントは、Experimental フォルダー内の
readme.mdファイルに記載する必要があります。 例: MRTK/SDK/Experimental/PulseShader/readme.md。Documentation/toc.ymlの Feature Overviews で、Experimental セクションにリンクを追加します。
MRTK コードへの影響を最小限に抑える
MRTK の変更によって実験が機能するようになる可能性はありますが、他のユーザーに思いもよらない影響が及ぶ可能性があります。 MRTK コア コードに対して行った回帰により、pull request が元に戻されることになります。
Experimental フォルダー以外のフォルダーには、変更を加えないことを目指してください。 実験的な変更を配置できるフォルダーの一覧を次に示します。
- MRTK/SDK/Experimental
- MRTK/SDK/Inspectors/Experimental
- MRTK/Examples/Experimental
これらのフォルダーの外部での変更は、慎重を期す必要があります。 実験的な機能を実現するために MRTK コア コードに変更を加える必要がある場合は、MRTK の変更を、テストとドキュメントを含む別の pull request に分割することを検討してください。
実験的な機能を使用することで、ユーザーがコア コントロールを使用できなくなるような事態は避ける必要があります
ほとんどのユーザーは、ボタン、ManipulationHandler、対話可能オブジェクトのようなコア UX コンポーネントを頻繁に使用します。 ボタンが使用できなくなるような場合、ユーザーはおそらくあなたの実験的な機能を使用しないでしょう。
あなたのコンポーネントを使用したために、ボタン、ManipulationHandler、BoundingBox、または対話可能オブジェクトが破損するような事態は避けてください。
たとえば、この ScrollableObjectCollection PR では、ScrollableObjectCollection を追加すると、HoloLens のボタン プレハブが使用できなくなりました。 これは PR のバグによって引き起こされたものではありませんが (むしろ既存のバグが明らかになったものです)、PR のチェックインは禁止されました。
機能の使用方法を示すシーンの例を提供する
ユーザーは、機能の使用方法とテスト方法を確認する必要があります。
MRTK/Examples/Experimental/
ユーザーの目に見える実験的機能の欠陥を最小限に抑える
動作せず、機能として成立していない場合、実験的な機能が使用されることはありません。
ターゲット プラットフォームでシーンの例をテストし、想定どおりに動作することを確認します。 機能がエディターでも動作することを確認します。これにより、ターゲット プラットフォームがない場合でも、ユーザーは迅速に反復処理して機能を確認できます。
実験的なコードを MRTK コードに昇格させる
機能が非常によく使用されている場合は、これをコア MRTK コードに昇格させることになります。 これを行うには、この機能にテスト、ドキュメント、およびシーンの例が含まれている必要があります。
機能を MRTK に昇格させる準備ができたら、PR でチェック対象のイシューを作成します。 PR には、これをコア機能にするために必要なすべてのもの (テスト、ドキュメント、使用方法を示すシーンの例) を含める必要があります。
また、必ず名前空間を更新して、"Experimental" サブスペースを削除してください。