Fitur eksperimental — MRTK2

  • Artikel

Beberapa fitur yang bekerja tim MRTK tampaknya memiliki banyak nilai awal bahkan jika kami belum sepenuhnya mengetahui detailnya. Untuk jenis fitur ini, kami ingin komunitas mendapatkan kesempatan untuk melihatnya lebih awal. Karena mereka berada di awal siklus, kami melabelinya sebagai eksperimental untuk menunjukkan bahwa mereka masih berkembang, dan dapat berubah dari waktu ke waktu.

Apa yang diharapkan dari fitur eksperimental

Jika komponen ditandai eksperimental, Anda dapat mengharapkan hal berikut:

  • Contoh adegan yang menunjukkan penggunaan, terletak di bawah MRTK/Examples/Experimental sub-folder
  • Fitur eksperimental mungkin tidak memiliki dokumen.
  • Mereka mungkin tidak memiliki tes.
  • Fitur eksperimental dapat berubah.

Panduan fitur eksperimental

Kode eksperimental harus hidup di folder terpisah

Kode eksperimental harus masuk ke folder eksperimental tingkat atas diikuti dengan nama fitur eksperimental. Misalnya, jika mencoba berkontribusi fitur baru FooBar, masukkan kode dalam hal berikut:

  • Contoh adegan, skrip masuk ke MRTK/Examples/Experimental/FooBar/
  • Skrip komponen, prefab masuk ke MRTK/SDK/Experimental/FooBar/
  • Pemeriksa komponen masuk ke MRTK/SDK/Inspectors/Experimental/FooBar

Saat menggunakan sub-folder di bawah nama fitur eksperimental, coba cerminkan struktur folder MRTK yang sama.

Misalnya, pemecah akan berada di bawah MRTK/SDK/Experimental/FooBar/Features/Utilities/Solvers/FooBarSolver.cs

Simpan adegan di folder adegan di dekat bagian atas: MRTK/Examples/Experimental/FooBar/Scenes/FooBarExample.unity

Catatan

Kami menganggap tidak memiliki satu folder akar Eksperimental dan sebaliknya menempatkan Eksperimental di bawah katakan MRTK/Examples/HandTracking/Scenes/Experimental/HandBasedMenuExample.unity. Kami memutuskan untuk menggunakan folder di pangkalan untuk membuat fitur eksperimental lebih mudah ditemukan.

Kode eksperimental harus berada di namespace khusus

Pastikan bahwa kode eksperimental berada di namespace eksperimental yang cocok dengan lokasi non-eksperimental. Misalnya, jika komponen Anda adalah bagian dari pemecah di Microsoft.MixedReality.Toolkit.Utilities.Solvers, namespace layanannya harus Microsoft.MixedReality.Toolkit.Experimental.Utilities.Solvers.

Lihat PR ini misalnya.

Fitur eksperimental harus memiliki atribut [Eksperimental]

[Experimental] Tambahkan atribut di atas salah satu bidang Anda agar dialog kecil muncul di editor komponen yang menyebutkan fitur Anda bersifat eksperimental dan dapat mengalami perubahan yang signifikan.

Pastikan bahwa fitur eksperimental berada di bawah sub-menu "eksperimental" saat menambahkan perintah ke menu di editor. Berikut beberapa contohnya:

Menambahkan perintah menu tingkat atas:

[MenuItem("Mixed Reality Toolkit/Experimental/MyCommand")]
public static void MyCommand()

Menambahkan menu komponen:

[AddComponentMenu("MRTK/Experimental/MyCommand")]

Dokumentasi

Ikuti langkah-langkah berikut untuk menambahkan dokumentasi untuk fitur eksperimental Anda:

  1. Dokumentasi apa pun untuk fitur eksperimental harus masuk ke readme.md file di folder eksperimental. Misalnya, MRTK/SDK/Experimental/PulseShader/readme.md.

  2. Di bawah Gambaran Umum Fitur Tambahkan tautan di bagian Eksperimental di Documentation/toc.yml.

Meminimalkan dampak ke kode MRTK

Meskipun perubahan MRTK Anda mungkin membuat eksperimen Anda berfungsi, itu dapat berdampak pada orang lain dengan cara yang tidak Anda harapkan. Setiap regresi yang Anda buat ke kode inti MRTK akan mengakibatkan permintaan pull Anda dikembalikan.

Bertujuan untuk memiliki nol perubahan dalam folder selain folder eksperimental. Berikut adalah daftar folder yang dapat memiliki perubahan eksperimental:

  • MRTK/SDK/Eksperimental
  • MRTK/SDK/Inspektur/Eksperimental
  • MRTK/Contoh/Eksperimental

Perubahan di luar folder ini harus diperlakukan dengan sangat hati-hati. Jika fitur eksperimental Anda harus menyertakan perubahan pada kode inti MRTK, pertimbangkan untuk memisahkan perubahan MRTK menjadi permintaan pull terpisah yang menyertakan pengujian dan dokumentasi.

Menggunakan fitur eksperimental Anda seharusnya tidak memengaruhi kemampuan orang untuk menggunakan kontrol inti

Sebagian besar orang menggunakan komponen UX inti seperti tombol , ManipulationHandler dan Interactable sangat sering. Mereka kemungkinan tidak akan menggunakan fitur eksperimental Anda jika mencegah mereka menggunakan tombol.

Menggunakan komponen Anda tidak boleh merusak tombol, ManipulationHandler, BoundingBox, atau dapat berinteraksi.

Misalnya, dalam PR ScrollableObjectCollection ini, menambahkan ScrollableObjectCollection menyebabkan orang tidak dapat menggunakan prefab tombol HoloLens. Meskipun ini tidak disebabkan oleh bug di PR (melainkan mengekspos bug yang ada), itu mencegah PR masuk.

Berikan contoh adegan yang menunjukkan cara menggunakan fitur

Orang perlu melihat cara menggunakan fitur Anda, dan cara mengujinya.

Berikan contoh di bawah MRTK/Contoh/Eksperimental/YOUR_FEATURE

Meminimalkan kelemahan yang terlihat pengguna dalam fitur eksperimental

Yang lain tidak akan menggunakan fitur eksperimental jika tidak berfungsi, itu tidak akan lulus ke fitur.

Uji contoh adegan Anda di platform target Anda, pastikan adegan tersebut berfungsi seperti yang diharapkan. Pastikan fitur Anda juga berfungsi di editor, sehingga orang dapat melakukan iterasi dengan cepat dan melihat fitur Anda meskipun mereka tidak memiliki platform target.

Meluluskan kode eksperimental ke dalam kode MRTK

Jika fitur akhirnya melihat cukup banyak penggunaan, maka kita harus lulus menjadi kode MRTK inti. Untuk melakukan ini, fitur harus memiliki pengujian, dokumentasi, dan contoh adegan.

Ketika Anda siap untuk lulus fitur MRTK, buat masalah untuk memeriksa PR Anda. PR harus mencakup semua hal yang diperlukan untuk menjadikan ini fitur inti: pengujian, dokumentasi, dan contoh adegan yang menunjukkan penggunaan.

Selain itu, jangan lupa untuk memperbarui namespace untuk menghapus subspace "Eksperimental".