Experimentální funkce

Zdá se, že některé funkce, na které tým MRTK pracuje, mají velkou počáteční hodnotu, i když jsme podrobnosti úplně nevypláceli. U těchto typů funkcí chceme, aby komunita měli příležitost je včas vidět. Vzhledem k tomu, že jsou v rané fázi cyklu, označujeme je jako experimentální, aby indikoval, že se stále vyvíjejí a že se v průběhu času mohou měnit.

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

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

  • Ukázková scéna demonstrující použití umístěná v MRTK/Examples/Experimental podsítě
  • 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 v samostatné složce.

Experimentální kód by měl jít do experimentální složky nejvyšší úrovně následované názvem experimentální funkce. Pokud se například pokoušíte přispět novou funkcí FooBar, dejte kód do následujícího kódu:

  • Příklady scén a skripty MRTK/Examples/Experimental/FooBar/
  • Skripty komponent, předběžné komponenty MRTK/SDK/Experimental/FooBar/
  • Inspektoři komponent se chytou do MRTK/SDK/Inspectors/Experimental/FooBar

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

Například řešiteeři budou v části MRTK/SDK/Experimental/FooBar/Features/Utilities/Solvers/FooBarSolver.cs

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

Poznámka

Zvážili jsme, že nemáme jednu experimentální kořenovou složku a místo toho jsme do ní zaměstnáme experimentální složku MRTK/Examples/HandTracking/Scenes/Experimental/HandBasedMenuExample.unity . Rozhodli jsme se pro složky v základu, aby se usnadnilo 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 se experimentální kód nachází v experimentálním oboru názvů, který odpovídá ne experimentálnímu umístění. Pokud je například vaše komponenta součástí řešitelů v Microsoft.MixedReality.Toolkit.Utilities.Solvers , její obor názvů by měl být Microsoft.MixedReality.Toolkit.Experimental.Utilities.Solvers .

Příklad najdete v této pr.

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

Přidáním atributu nad jedno z polí zobrazíte v editoru komponent malý dialog, který zmiňuje, že vaše funkce je experimentální a podléhá [Experimental] významným změnám.

Při přidávání příkazů do nabídek v editoru se ujistěte, že experimentální funkce jsou pod experimentálními podnabídky. 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 komponenty:

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

Dokumentace

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

  1. Jakákoli dokumentace k experimentální funkci by měla být v readme.md souboru v experimentální složce. Například MRTK/SDK/Experimental/PulseShader/readme.md.

  2. V části Přehledy funkcí v části Experimentální na stránce přidejte Documentation/toc.yml odkaz.

Minimalizace dopadu na kód MRTK

I když by vaše změna MRTK mohla váš experiment zmát, mohl by ovlivnit jiné lidi způsoby, které neočekáváte. Všechny regrese základního kódu MRTK by vedlo k tomu, že se vaše žádost o změnu vrátí zpět.

Zaměřte se na nulovou změnu jiných složek než experimentálních složek. Tady je seznam složek, které mohou mít experimentální změny:

  • MRTK/SDK/Experimentální
  • MRTK/SDK/Inspectors/Experimental
  • MRTK/ Příklady / Experimentální

Se změnami mimo tyto složky by se mělo zacházet velmi opatrně. Pokud vaše experimentální funkce musí obsahovat změny základního kódu MRTK, zvažte rozdělení změn MRTK do samostatné žádosti o vyžádání, která zahrnuje testy a dokumentaci.

Používání experimentální funkce by nemělo mít vliv na schopnost lidí používat základní ovládací prvky.

Většina lidí velmi často používá základní součásti uživatelského rozhraní, jako je tlačítko, ManipulationHandler a Interactable. Vaše experimentální funkce pravděpodobně nebudou používat, pokud jim zabrání v používání tlačítek.

Použití komponenty by nemělo přerušit tlačítka, ManipulationHandler, BoundingBox ani interagovat.

Například v této vlastnosti ScrollableObjectCollection PRpřidání objektu ScrollableObjectCollection způsobilo, že lidé HoloLens tlačítka použít. I když to nebyla způsobená chybou v pr (ale místo toho, aby se odhalila existující chyba), zabránila tomu, aby se pr ohlásila.

Uveďte příklad scény, která ukazuje, jak funkci používat.

Lidé musí vědět, jak funkci používat a jak ji otestovat.

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

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

Ostatní nebudou experimentální funkci používat, pokud nefunguje, ale nepřechádnou k funkci.

Otestujte svou příkladovou scénu na cílové platformě a ujistěte se, že funguje podle očekávání. Ujistěte se, že vaše funkce funguje také v editoru, aby lidé mohli rychle iterovat a vidět vaši funkci, i když nemají cílovou platformu.

Přechod experimentálního kódu na kód MRTK

Pokud se funkce nakonec hodně využije, měli bychom ji přenechat do základního kódu MRTK. K tomu by funkce měla mít testy, dokumentaci a příklad scény.

Až budete připraveni tuto funkci mrtk vyřešit, vytvořte problém, se kterou se můžete o něco podívat. Tato pr by měla zahrnovat všechny věci potřebné k tomu, aby se z této základní funkce těžily testy, dokumentace a příklad scény znázorňující využití.

Nezapomeňte také aktualizovat obory názvů a odebrat tak podprostor Experimentální.