MRTK3 への貢献

  • [アーティクル]

MRTK3 は、MIT ライセンスのオープンソース プロジェクトです。 新機能の追加やバグ修正など、コミュニティへの貢献はいずれも歓迎され、高く評価されます。

MRTK3 に貢献するのは簡単です。 Unity プロジェクトは MRTKDevTemplate 、すべての MRTK3 パッケージをローカルのディスク上の依存関係として既に含んでいるため、便利な開発テストベッドとして使用することをお勧めします。 サンプル シーンとローカルのディスク上の依存の詳細については、MRTKDevTemplate プロジェクトに関するドキュメントを参照してください。

貢献ガイド

  1. MRTK リポジトリを GitHub アカウントにフォークします。

  2. テンプレート プロジェクトからの開始に関するガイドに従って、フォークした MRTK リポジトリを複製します。必要なツール、特に正しい Unity バージョンがあることを確認してください。 正しいブランチに確実にアクセスするために、以下のコマンドを使用して複製します。

git clone --branch mrtk3 YOUR_GIT_URL
  1. 変更または修正のために新しいブランチを作成します。
git checkout -b yourchange_fix

  1. UnityProjects/MRTKDevTemplate にある MRTKDevTemplate テンプレート プロジェクトを開きます。 簡単にアクセスできるように、プロジェクトを Unity Hub に追加できます。

  2. 必要な変更を行い、その変更が期待どおりに動作することを確認する単体テストを作成します。 エディター内とデバイスへのデプロイにわたってテストするようにしてください。 変更をブランチにコミットします。 ブランチをフォークのアップストリームに発行します。

  3. MRTK リポジトリで mrtk3 ブランチをターゲットとして pull request を開きます。 行った変更を正確に記述し、適切なラベルをプルリクエストに適用して、分類とトリアージを改善してください。 MRTK の新しい共同作成者である場合は、コントリビューション契約に署名する必要がある場合があります。

  4. コミュニティまたはメンテナンス チームから要求された修正に対処し、承認後に PR をマージします。

テストを作成する

テストは、MRTK が高品質の Mixed Reality アプリケーションのための信頼性の高い基盤であることを確認する上で重要な部分です。 追加された新しい機能は、将来的にコードベースに他の変更が加えられたときに、その機能が正しいままであることを保証するための単体テストが必要です。

単体テストを記述するには、まず既存の単体テストを確認し、MRTK テスト ユーティリティとシミュレーターを使用して XR 入力をモックする方法を学習することをお勧めします。 手入力、視線入力、HMD の位置、その他の基本的な入力関連の機能をモックできます。 優れた単体テストを書くための一般的なアドバイスを次に紹介します。

  • 大きな単体テストではなく、より小さな機能の断片を評価するような、粒度の細かいテストを書くようにします。 より粒度の細かい単体テストを書くことで、メンテナンス担当者はどの機能が破損しているのかを確認できます。 より一般的なエンドツーエンドの機能テストも評価されますが、機能の各小さな部分が最初に十分にテストされていることを確認してください。
  • テスト (および機能) では、ユーザーの向きや場所に関する仮定が行われないようにします。 テストと機能は、ワールド原点からの任意のオフセットや回転で機能する必要があります。
  • ユーザー入力を模擬するテストを行う場合は、必ず BaseRuntimeInputTests をサブクラス化してください。これにより、適切なテスト ハーネスが設定され、破棄されます。
  • NUnit のパラメーター化を使って、テストの多様性と柔軟性を簡単に向上できます。 パラメーター化された NUnit テストについては、こちらのドキュメントを参照してください。
  • 入力や対話式操作の中には、登録に複数のフレームが必要になるものがあります。 対話式操作が登録されていない場合は、yield return RuntimeTestUtilities.WaitForUpdates() を使ってテストに遅延フレームを追加できます。
  • CI の反復時間が遅くなるのを防ぐために、できるだけ早く実行される単体テストを書くようにします。
  • 関連するテストの依存関係が package.json に追加され、テスト フォルダーのアセンブリ定義ファイルに正しい参照が追加されていることを確認します。

継続的インテグレーション

すべての pull request は、マージされる前に自動テストの対象となります。 また、破損したパッケージがフィードにデプロイされないように、メイン開発ブランチでの結果のコミットに対して継続的インテグレーション (CI) の追加ジョブが実行されます。

テストがエディター上で成功しても CI の実行で失敗した場合は、バッチ モードでローカルでのテストを実行する必要があります。 一部の種類のテストは、タイミングの違いや他の Unity の特異な性質のために、グラフィックスなしのバッチ モードで実行すると予期せず失敗することがあります。 バッチ モードでローカルでのテストを実行することで、CI が実行される前にこれらの一貫性のないテストを特定するのに役立ちます。

バッチ モードでローカルでのテストを実行するには、Tooling/Tests/run_playmode_tests.ps1 スクリプトを使います。 これを行うには、Unity エディターを閉じる必要があります。

$ ./Tooling/Tests/run_playmode_tests.ps1

スクリプトは /out フォルダーに、.log ファイルとテスト結果の .xml の両方を含む出力ファイルを生成します。 スクリプトに正規表現を渡すことで、実行されるテストをフィルター処理できます。 カスタムの Unity バージョンとプロジェクト フォルダーの場所を引数として指定することもできます。

$ ./Tooling/Tests/run_playmode_tests.ps1 -unityVersion 2021.3.5f1 -projectPath ../my/project/path