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ě:
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.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í.