Experimentální funkce – MRTK2

Zdá se, že některé funkce, na kterých tým MRTK pracuje, mají velkou počáteční hodnotu, i když jsme ještě úplně nevyužili podrobnosti. U těchto typů funkcí chceme, aby je komunita viděla co nejdříve. Vzhledem k tomu, že jsou v rané fázi cyklu, označíme je jako experimentální, což značí, že se stále vyvíjejí a mohou se v průběhu času 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í:

• Příklad scény demonstrující použití, která se nachází v MRTK/Examples/Experimental podsložce
• Experimentální funkce nemusí obsahovat dokumenty.
• Pravděpodobně nemají testy.
• Experimentální funkce se můžou 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 přejí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, vložte kód do následujícího:

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

Při použití podsložek pod názvem experimentální funkce zkuste zrcadlit stejnou strukturu složek MRTK.

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

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

Poznámka

Zvážili jsme, že nemáme jednu kořenovou složku Experimentální a místo toho jsme experimentální umístili pod řekněme MRTK/Examples/HandTracking/Scenes/Experimental/HandBasedMenuExample.unity. Rozhodli jsme se použít složky v základu, abychom usnadnili 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 je v experimentálním oboru názvů, který odpovídá umístění, které není experimentální. Pokud je například vaše komponenta součástí řešitelů na adrese 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 žádosti o přijetí změn.

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

[Experimental] Přidejte atribut nad jedno z polí, aby se v editoru komponent zobrazilo malé dialogové okno, které uvádí, že vaše funkce je experimentální a může se výrazně změnit.

Nabídky experimentálních funkcí by měly být v podnábídce Experimentální.

Při přidávání příkazů do nabídek v editoru se ujistěte, že jsou experimentální funkce v dílčích nabídkách "experimentální". 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 komponent:

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

Dokumentace

Pokud chcete přidat dokumentaci k experimentální funkci, postupujte následovně:

1. Veškerá 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í přidejte odkaz v části Experimentální na adrese Documentation/toc.yml.

Minimalizace dopadu na kód MRTK

I když vaše změna MRTK může váš experiment fungovat, může to mít vliv na ostatní uživatele způsobem, který neočekáváte. Jakékoli regrese, které provedete u základního kódu MRTK, způsobí vrácení vaší žádosti o přijetí změn.

Snažte se, aby v jiných než experimentálních složkách nebyly žádné změny. Tady je seznam složek, které můžou mít experimentální změny:

• MRTK/SDK/Experimentální
• MRTK/SDK/Inspectors/Experimental
• MRTK/Examples/Experimental

Změny mimo tyto složky by se měly zpracovávat velmi opatrně. Pokud experimentální funkce musí obsahovat změny základního kódu MRTK, zvažte rozdělení změn MRTK na samostatnou žádost o přijetí změn, která zahrnuje testy a dokumentaci.

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

Většina lidí velmi často používá základní komponenty uživatelského prostředí, jako je tlačítko, ManipulatHandler a Interactable. Pokud jim brání používat tlačítka, pravděpodobně nebudou používat vaši experimentální funkci.

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

Například v této žádosti o přijetí změn scrollableObjectCollection přidání ScrollableObjectCollection způsobilo, že lidé nemohli používat prefabs tlačítka HoloLens. I když to nebylo způsobeno chybou v žádosti o přijetí změn (ale spíše odhalilo existující chybu), zabránilo to žádosti o přijetí změn se změnami.

Uveďte ukázkovou scénu, která ukazuje, jak funkci používat.

Lidé potřebovat zjistit, jak funkci používat a jak ji otestovat.

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

Minimalizace chyb viditelných uživatelem v experimentálních funkcích

Jiní uživatelé nebudou experimentální funkci používat, pokud nebude fungovat, ale nebude na funkci přechádět.

Otestujte ukázkovou 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 uživatelé mohli rychle iterovat a vidět vaši funkci, i když nemají cílovou platformu.

Absolvování experimentálního kódu na kód MRTK

Pokud se funkce nakonec hodně používá, měli bychom ji převést do základního kódu MRTK. K tomu by funkce měla mít testy, dokumentaci a ukázkovou scénu.

Až budete připraveni absolvovat funkci MRTK, vytvořte problém, který se má v žádosti o přijetí změn ověřit. Žádost o přijetí změn by měla obsahovat všechny věci potřebné k tomu, aby se z toho udělala základní funkce: testy, dokumentace a ukázková scéna znázorňující použití.

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