Experimentální funkce

Některé funkce, na kterých tým MRTK funguje, se zdají mít spoustu počáteční hodnoty, a to i v případě, že jsme úplné podrobnosti neudělali. Pro tyto typy funkcí chceme, aby se komunita dostala do brzkého zobrazení. Vzhledem k tomu, že jsou v předstihu v cyklu, označíme je jako experimentální, aby označovaly, že se stále vyvíjí a že se mohou v průběhu času měnit.

Co očekávat od experimentální funkce

Pokud je součást označena jako experimentální, můžete očekávat následující:

  • Ukázková scéna ukazující použití, která se nachází v MRTK/Examples/Experimental podsložkách
  • Experimentální funkce nemusí mít dokumenty.
  • Pravděpodobně nemají testy.
  • Experimentální funkce se mohou změnit.

Pokyny k experimentálním funkcím

Experimentální kód by měl být živý v samostatné složce.

Experimentální kód by měl přejít do experimentální složky nejvyšší úrovně následovanou experimentálním názvem funkce. Například pokud se snažíte přispívat k nové funkci panel, vložte kód do následujícího:

  • Ukázkové scény, skripty přejít do MRTK/Examples/Experimental/FooBar/
  • Skripty komponent, prefabs přejít do MRTK/SDK/Experimental/FooBar/
  • Inspektory komponent – přejít do MRTK/SDK/Inspectors/Experimental/FooBar

Pokud používáte podsložky s názvem experimentální funkce, zkuste zrcadlit stejnou strukturu složek MRTK.

Například Řešitelé by přecházejí pod MRTK/SDK/Experimental/FooBar/Features/Utilities/Solvers/FooBarSolver.cs

Zachovat scény ve složce scény v horní části: MRTK/Examples/Experimental/FooBar/Scenes/FooBarExample.unity

Poznámka

Nepovažujeme se za jednu experimentální kořenovou složku a místo toho je třeba uvést do provozu experimentální údaje MRTK/Examples/HandTracking/Scenes/Experimental/HandBasedMenuExample.unity . Rozhodli jste se používat složky se základními funkcemi, které usnadňují zjišťování experimentálních funkcí.

Experimentální kód by měl být ve speciálním oboru názvů.

Ujistěte se, že experimentální kód bydlí v experimentálním oboru názvů, který odpovídá neexperimentálnímu umístění. Například pokud je vaše komponenta součástí řešitelů Microsoft.MixedReality.Toolkit.Utilities.Solvers , měl by mít jeho obor názvů Microsoft.MixedReality.Toolkit.Experimental.Utilities.Solvers .

Příklad najdete v této žádosti o přijetí změn.

Experimentální funkce by měly mít atribut [experimentální].

Přidejte [Experimental] atribut nad jedno z polí, aby v editoru komponent byl zobrazen malý dialog, který uvádí, že vaše funkce je experimentální a podléhá významným změnám.

Zajistěte, aby se experimentální funkce v rámci "experimentálních" podnabídek při přidávání příkazů do nabídek v editoru. Tady je pár příkladů:

Přidání příkazu nabídky nejvyšší úrovně:

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

Přidání nabídky součásti:

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

Dokumentace

Pomocí těchto kroků přidejte dokumentaci k experimentální funkci:

  1. Dokumentace k experimentální funkci by měla přejít do readme.md souboru v experimentální složce. Například MRTK/SDK/experimentální/PulseShader/Readme. MD.

  2. V části přehledy funkcí přidejte odkaz v experimentální části na .

Minimalizace dopadu na MRTK kód

I když se změna MRTK může experimentovat, může to mít vliv na jiné lidi způsobem, jakým jste neočekávali. Jakákoli regrese, kterou provedete v kódu MRTK Core, by způsobila, že se vaše žádost o přijetí změn vrátila zpět.

Zacílení na nenulové změny ve složkách jiných než experimentální složky. Tady je seznam složek, které mohou mít experimentální změny:

  • MRTK/SDK/experimentální
  • MRTK/SDK/inspektoři/experimentální
  • MRTK/příklady/experimentální

Změny mimo tyto složky by se měly považovat za velmi pečlivě. Pokud vaše experimentální funkce musí zahrnovat změny MRTK základního kódu, zvažte rozdělení MRTK změn do samostatné žádosti o přijetí změn, která zahrnuje testy a dokumentaci.

Použití experimentálních funkcí by nemělo mít vliv na schopnost uživatelů používat základní ovládací prvky.

Většina lidí používá základní součásti uživatelského prostředí, jako je tlačítko, ManipulationHandler a umožňuje velmi častou práci. Pokud jim zabrání v použití tlačítek, nebude nejspíš vaše experimentální funkce používat.

Použití vaší komponenty by nemělo rušit tlačítka, ManipulationHandler, BoundingBox nebo pracovat.

například v tomto ScrollableObjectCollectionžádosti o přijetí změn přidáním ScrollableObjectCollection, že lidé nebudou moci používat HoloLens tlačítko prefabs. I když to nebylo způsobené chybou v žádosti o přijetí změn (ale místo toho zveřejnění stávající chyby), zabránilo se vrácení žádosti o přijetí změn v žádosti o přijetí změn.

Zadejte příklad scény, který ukazuje, jak používat funkci.

Lidé musí vidět, jak používat vaši funkci, a jak ji otestovat.

Zadejte příklad v části MRTK/Examples/experimentální/YOUR_FEATURE

Minimalizace viditelných vad uživatelů v experimentálních funkcích

Pokud tato funkce nefunguje, neprojeví se funkce experimentální.

Otestujte ukázkovou scénu na cílové platformě a ujistěte se, že funguje podle očekávání. Ujistěte se, že funkce funguje i v editoru, takže lidé můžou rychle iterovat a zobrazovat vaši funkci i v případě, že nemají cílovou platformu.

Propromoení experimentálního kódu do MRTK kódu

Pokud funkce ukončí hodně použití, měli byste ji dopracovat do základního kódu MRTK. Tato funkce by měla mít testy, dokumentaci a ukázkovou scénu.

Až budete připraveni k absolvování funkce MRTK, vytvořte problém pro vrácení žádosti o přijetí změn. Žádost o přijetí změn by měla obsahovat všechny věci potřebné k tomu, aby tato funkce byla základní: testy, dokumentace a ukázková scéna zobrazující využití.

Nezapomeňte taky aktualizovat obory názvů tak, aby se odebralo "experimentální" místo.