Funkcje eksperymentalne — MRTK2

Niektóre funkcje, na których pracuje zespół MRTK, wydają się mieć dużą wartość początkową, nawet jeśli nie w pełni ułożone szczegóły. W przypadku tych typów funkcji chcemy, aby społeczność szybko je zobaczyła. Ponieważ są one na początku cyklu, oznaczymy je jako eksperymentalne, aby wskazać, że są one nadal ewoluujące i mogą ulec zmianie w miarę upływu czasu.

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 przedstawiająca użycie znajdujące się w MRTK/Examples/Experimental podfolderze
• Funkcje eksperymentalne mogą nie zawierać dokumentów.
• Prawdopodobnie nie mają testów.
• Funkcje eksperymentalne mogą ulec zmianie.

Wskazówki dotyczące funkcji eksperymentalnych

Kod eksperymentalny powinien znajdować się w osobnym folderze

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

• Przykładowe sceny, skrypty przechodzą do MRTK/Examples/Experimental/FooBar/
• Skrypty składników, prefabryki przechodzą do MRTK/SDK/Experimental/FooBar/
• Inspektorzy składników przechodzą do MRTK/SDK/Inspectors/Experimental/FooBar

W przypadku używania podfolderów w ramach eksperymentalnej nazwy funkcji spróbuj zdublować tę samą strukturę folderów zestawu narzędzi MRTK.

Na przykład moduły rozwiązywania będą przechodzić w fazie MRTK/SDK/Experimental/FooBar/Features/Utilities/Solvers/FooBarSolver.cs

Zachowaj sceny w folderze sceny u góry: MRTK/Examples/Experimental/FooBar/Scenes/FooBarExample.unity

Uwaga

Uznaliśmy, że nie ma jednego folderu głównego eksperymentalnego i zamiast tego umieszczamy element Eksperymentalny pod adresem MRTK/Examples/HandTracking/Scenes/Experimental/HandBasedMenuExample.unity. Postanowiliśmy przejść z folderami w bazie, aby ułatwić odnajdywanie funkcji eksperymentalnych.

Kod eksperymentalny powinien znajdować się w specjalnej przestrzeni nazw

Upewnij się, że kod eksperymentalny znajduje się w eksperymentalnej przestrzeni nazw zgodnej z lokalizacją nie eksperymentalną. Jeśli na przykład składnik jest częścią modułów rozwiązywania w lokalizacji Microsoft.MixedReality.Toolkit.Utilities.Solvers, jego przestrzeń nazw powinna mieć wartość Microsoft.MixedReality.Toolkit.Experimental.Utilities.Solvers.

Zobacz ten przykład żądania ściągnięcia .

Funkcje eksperymentalne powinny mieć atrybut [Eksperymentalny]

[Experimental] Dodaj atrybut powyżej jednego z pól, aby w edytorze składników pojawiło się małe okno dialogowe, które wskazuje, że funkcja jest eksperymentalna i może ulec znaczącym zmianom.

Menu dla funkcji eksperymentalnych powinny znajdować się w menu podrzędnym "Eksperymentalne"

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

Dodawanie polecenia menu najwyższego poziomu:

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

Dodawanie menu składników:

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

Dokumentacja

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

1. Każda dokumentacja funkcji eksperymentalnej powinna znajdować się w 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 pod adresem Documentation/toc.yml.

Minimalizowanie wpływu na kod MRTK

Chociaż zmiana zestawu narzędzi MRTK może spowodować, że eksperyment będzie działać, może to mieć wpływ na inne osoby w sposób, którego nie oczekujesz. Wszelkie regresje utworzone w kodzie podstawowym zestawu narzędzi MRTK spowodują przywrócenie żądania ściągnięcia.

Staraj się mieć zerowe zmiany w folderach innych niż foldery eksperymentalne. Oto lista folderów, które mogą mieć zmiany eksperymentalne:

• ZESTAW MRTK/SDK/eksperymentalny
• MRTK/SDK/Inspectors/Experimental
• MRTK/Przykłady/Eksperymentalne

Zmiany poza tymi folderami powinny być bardzo starannie traktowane. Jeśli funkcja eksperymentalna musi zawierać zmiany w kodzie podstawowym zestawu narzędzi MRTK, rozważ podzielenie zmian zestawu narzędzi MRTK na oddzielne żądanie ściągnięcia, które obejmuje testy i dokumentację.

Korzystanie z funkcji eksperymentalnej nie powinno wpływać na zdolność osób do korzystania z podstawowych kontrolek

Większość osób korzysta z podstawowych składników środowiska użytkownika, takich jak przycisk, Program Manipulowanie i Interakcja bardzo często. Prawdopodobnie nie będą korzystać z funkcji eksperymentalnej, jeśli uniemożliwia korzystanie z przycisków.

Użycie składnika nie powinno przerywać przycisków, programu ManipulationHandler, boundingBox ani interakcji.

Na przykład w tym żądaniu ściągnięcia ScrollableObjectCollection dodanie obiektu ScrollableObjectCollection spowodowało, że osoby nie mogą używać prefab przycisków HoloLens. Mimo że nie było to spowodowane usterką żądania ściągnięcia (ale raczej uwidoczniła istniejącą usterkę), uniemożliwiła zaewidencjonowaniu żądania ściągnięcia.

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

Osoby sprawdzić, jak używać funkcji i jak ją przetestować.

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

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

Inni nie będą używać funkcji eksperymentalnej, jeśli nie działa, nie zostanie ona ukończona do funkcji.

Przetestuj przykładowy scenę na platformie docelowej, upewnij się, że działa zgodnie z oczekiwaniami. Upewnij się, że funkcja działa również w edytorze, aby użytkownicy mogli szybko iterować i wyświetlać swoją funkcję, nawet jeśli nie mają platformy docelowej.

Ukończenie kodu eksperymentalnego do kodu MRTK

Jeśli funkcja kończy się na dość dużym użyciu, powinniśmy ukończyć ją w podstawowym kodzie MRTK. W tym celu funkcja powinna mieć testy, dokumentację i przykładową scenę.

Gdy wszystko będzie gotowe do ukończenia funkcji MRTK, utwórz problem w celu zaewidencjonowania żądania ściągnięcia. Żądanie ściągnięcia powinno zawierać wszystkie elementy potrzebne do utworzenia podstawowej funkcji: testów, dokumentacji i przykładowej sceny przedstawiającej użycie.

Ponadto nie zapomnij zaktualizować przestrzeni nazw, aby usunąć podprzestrzeń "eksperymentalną".