Funkcje eksperymentalne

Wydaje się, że niektóre funkcje, nad których pracuje zespół MRTK, mają dużą wartość początkową, nawet jeśli nie w pełni szczegółowo oswamialiśmy się ze szczegółami. W przypadku tego typu funkcji chcemy, aby społeczność zyskała możliwość ich wczesnego zobaczenia. Ponieważ są one na wczesnym etapie cyklu, oznaczamy je jako eksperymentalne, aby wskazać, że nadal ewoluują i mogą z czasem ulec zmianie.

Czego można oczekiwać od funkcji eksperymentalnej

Jeśli składnik jest oznaczony jako eksperymentalny, można oczekiwać następujących elementów:

  • Przykładowa scena pokazująca użycie znajdująca się w MRTK/Examples/Experimental podfoldeecie
  • Funkcje eksperymentalne mogą nie mieć dokumentów.
  • Prawdopodobnie nie mają testów.
  • Funkcje eksperymentalne mogą ulec zmianie.

Wytyczne dotyczące funkcji eksperymentalnych

Kod eksperymentalny powinien być na żywo w oddzielnym folderze

Kod eksperymentalny powinien trafić do folderu eksperymentalnego najwyższego poziomu, po którym następuje nazwa funkcji eksperymentalnej. Jeśli na przykład próbujesz współtworząc nową funkcję FooBar, umieść kod w następującym kodzie:

  • Przykładowe sceny, do których trafiają skrypty MRTK/Examples/Experimental/FooBar/
  • Skrypty składników, prefabrykaty są MRTK/SDK/Experimental/FooBar/
  • Inspektorzy składników MRTK/SDK/Inspectors/Experimental/FooBar

W przypadku używania podfolderów pod nazwą funkcji eksperymentalnej spróbuj dublować tę samą strukturę folderów zestawu danych MRTK.

Na przykład solvers would go under MRTK/SDK/Experimental/FooBar/Features/Utilities/Solvers/FooBarSolver.cs

Zachowaj sceny w folderze sceny w górnej części: MRTK/Examples/Experimental/FooBar/Scenes/FooBarExample.unity

Uwaga

Rozważyliśmy, że nie mamy jednego eksperymentalnego folderu głównego i zamiast tego umieszczamy w obszarze Najsuchom eksperymentalne MRTK/Examples/HandTracking/Scenes/Experimental/HandBasedMenuExample.unity powiedzmy . Postanowiliśmy przejść z folderami w bazie, aby ułatwić odnajdywanie funkcji eksperymentalnych.

Kod eksperymentalny powinien być w specjalnej przestrzeni nazw

Upewnij się, że kod eksperymentalny znajduje się w eksperymentalnej przestrzeni nazw, która pasuje do lokalizacji nie eksperymentalnej. Jeśli na przykład składnik jest częścią składników rozwiązywania w katalogu Microsoft.MixedReality.Toolkit.Utilities.Solvers , jego przestrzenią nazw powinna być Microsoft.MixedReality.Toolkit.Experimental.Utilities.Solvers .

Zobacz to ściągnięcie ściągnięcie, aby uzyskać przykład.

Funkcje eksperymentalne powinny mieć atrybut [Eksperymentalne]

Dodaj atrybut powyżej jednego z pól, aby w edytorze składników było wyświetlane małe okno dialogowe z informacjami o tym, że funkcja jest eksperymentalna i podlega [Experimental] istotnym zmianom.

Upewnij się, że funkcje eksperymentalne znajdują się w menu podrzędnym "eksperymentalnym" podczas dodawania poleceń do menu w edytorze. Oto kilka przykładów:

Dodanie polecenia menu najwyższego poziomu:

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

Dodawanie menu składnika:

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

Dokumentacja

Wykonaj następujące kroki, aby dodać dokumentację dla funkcji eksperymentalnej:

  1. Każda dokumentacja funkcji eksperymentalnej powinna trafić do readme.md pliku w folderze eksperymentalnym. Na przykład MRTK/SDK/Experimental/PulseShader/readme.md.

  2. W obszarze Przeglądy funkcji Dodaj link w sekcji Eksperymentalne na stronie Documentation/toc.yml .

Minimalizowanie wpływu na kod MRTK

Chociaż zmiana mrTK może spowodować, że eksperyment będzie działać, może to wpłynąć na inne osoby w sposób, który nie jest spodziewany. Wszelkie regresje w kodzie podstawowym MRTK będą powodować cofnięcie żądania ściągnnięcia.

Staraj się nie wprowadzać żadnych zmian w folderach innych niż foldery eksperymentalne. Poniżej znajduje się lista folderów, które mogą mieć eksperymentalne zmiany:

  • ZESTAW MRTK/ZESTAW SDK/Eksperymentalne
  • ZESTAW MRTK/ZESTAW SDK/Inspektorzy/Eksperymentalne
  • MRTK/Examples/Experimental

Zmiany poza tymi folderami należy traktować bardzo ostrożnie. Jeśli funkcja eksperymentalna musi zawierać zmiany w kodzie podstawowym zestawu danych MRTK, rozważ podzielenie zmian zestawu mrTK na oddzielne żądanie ściągnięcie, które zawiera testy i dokumentację.

Korzystanie z funkcji eksperymentalnej nie powinno mieć wpływu na możliwość używania podstawowych kontrolek przez ludzi

Większość osób używa podstawowych składników środowiska użytkownika, takich jak przycisk ManipulationHandler i Interactable, bardzo często. Prawdopodobnie nie będą używać funkcji eksperymentalnej, jeśli uniemożliwi to im korzystanie z przycisków.

Użycie składnika nie powinno łamać przycisków, Elementu ManipulationHandler, BoundingBox ani interakcji.

Na przykład w tym pniu ściągnięcia ScrollableObjectCollectiondodanie funkcji ScrollableObjectCollection powodowało, że ludzie nie mogli używać prefabrykcji HoloLens przycisku przewijania. Mimo że nie zostało to spowodowane przez usterkę w pryskaniu ściągniętym (ale raczej spowodowała narażenie istniejącej usterki), uniemożliwiło to zaewidencjonowanie tego błędu.

Podaj przykładową scenę, która pokazuje, jak używać funkcji

Ludzie muszą zobaczyć, jak korzystać z funkcji i jak ją przetestować.

Podaj przykład w obszarze MRTK/Examples/Experimental/YOUR_FEATURE

Minimalizowanie błędów widocznych dla użytkownika w funkcjach eksperymentalnych

Inne nie będą używać funkcji eksperymentalnej, jeśli nie będzie działać, nie zostaną one nadsyłane do funkcji.

Przetestuj przykładową scenę na platformie docelowej i upewnij się, że działa ona zgodnie z oczekiwaniami. Upewnij się, że funkcja działa również w edytorze, dzięki czemu ludzie mogą szybko iterować i widzieć tę funkcję, nawet jeśli nie mają platformy docelowej.

Ukończenie kodu eksperymentalnego do kodu MRTK

Jeśli funkcja jest już bardzo często używana, powinniśmy ją wchłonić do podstawowego kodu zestawu danych MRTK. W tym celu funkcja powinna mieć testy, dokumentację i przykładową scenę.

Gdy wszystko będzie gotowe do utworzenia zestawu mrtk funkcji, utwórz problem, przed którym należy sprawdzić swoje ściągnięcie. To wymaganie ściągnięcie powinno obejmować wszystkie rzeczy potrzebne do jej podstawowej funkcji: testy, dokumentację i przykładową scenę przedstawiającą użycie.

Nie zapomnij również zaktualizować przestrzeni nazw, aby usunąć przestrzeń podrzędną "Eksperymentalne".