Experimentella funktioner – MRTK2

Vissa funktioner som MRTK-teamet arbetar med verkar ha ett stort initialt värde även om vi inte har skapat detaljerna helt och hållet. För de här typerna av funktioner vill vi att communityn ska få en chans att se dem tidigt. Eftersom de är tidiga i cykeln märker vi dem som experimentella för att indikera att de fortfarande utvecklas och kan komma att ändras över tid.

Vad du kan förvänta dig av en experimentell funktion

Om en komponent är markerad som experimentell kan du förvänta dig följande:

• En exempelscen som visar användning, som finns under MRTK/Examples/Experimental undermappen
• Experimentella funktioner kanske inte har dokument.
• De har förmodligen inte tester.
• Experimentella funktioner kan komma att ändras.

Riktlinjer för experimentella funktioner

Experimentell kod bör finnas i en separat mapp

Experimentell kod bör gå till en experimentell mapp på den översta nivån följt av det experimentella funktionsnamnet. Om du till exempel försöker bidra med en ny funktion FooBar lägger du till kod i följande:

• Exempelscener, skript hamnar i MRTK/Examples/Experimental/FooBar/
• Komponentskript, prefabriceringar hamnar i MRTK/SDK/Experimental/FooBar/
• Komponentkontrollanter går in på MRTK/SDK/Inspectors/Experimental/FooBar

När du använder undermappar under namnet på den experimentella funktionen kan du försöka spegla samma mappstruktur för MRTK.

Till exempel skulle lösare gå under MRTK/SDK/Experimental/FooBar/Features/Utilities/Solvers/FooBarSolver.cs

Behåll scener i en scenmapp längst upp: MRTK/Examples/Experimental/FooBar/Scenes/FooBarExample.unity

Anteckning

Vi övervägde att inte ha en enda experimentell rotmapp och i stället placera Experimental under say MRTK/Examples/HandTracking/Scenes/Experimental/HandBasedMenuExample.unity. Vi bestämde oss för att gå med mappar på basen för att göra de experimentella funktionerna enklare att upptäcka.

Experimentell kod ska finnas i ett särskilt namnområde

Se till att den experimentella koden finns i ett experimentellt namnområde som matchar den icke-experimentella platsen. Om din komponent till exempel är en del av lösare på Microsoft.MixedReality.Toolkit.Utilities.Solversska dess namnområde vara Microsoft.MixedReality.Toolkit.Experimental.Utilities.Solvers.

Se den här pull-begäran för ett exempel.

Experimentella funktioner bör ha ett [experimentellt] attribut

Lägg till ett [Experimental] attribut ovanför ett av dina fält så att en liten dialogruta visas i komponentredigeraren som nämner att din funktion är experimentell och kan komma att ändras avsevärt.

Menyer för experimentella funktioner bör gå under undermenyn "Experimentell"

Se till att experimentella funktioner finns under "experimentella" undermenyer när du lägger till kommandon i menyer i redigeraren. Några exempel:

Lägga till ett menykommando på den översta nivån:

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

Lägga till en komponentmeny:

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

Dokumentation

Följ de här stegen för att lägga till dokumentation för din experimentella funktion:

1. All dokumentation för en experimentell funktion bör finnas i en readme.md fil i den experimentella mappen. Till exempel MRTK/SDK/Experimental/PulseShader/readme.md.

2. Under Funktionsöversikter Lägger du till en länk i avsnittet Experimentell på Documentation/toc.yml.

Minimera påverkan på MRTK-kod

Din MRTK-ändring kan få experimentet att fungera, men det kan påverka andra på sätt som du inte förväntar dig. Eventuella regressioner som du gör till MRTK-kärnkoden skulle leda till att pull-begäran återställs.

Sikta på att ha noll ändringar i andra mappar än experimentella mappar. Här är en lista över mappar som kan ha experimentella ändringar:

• MRTK/SDK/Experimentell
• MRTK/SDK/Inspectors/Experimental
• MRTK/Exempel/Experimentell

Ändringar utanför dessa mappar bör behandlas mycket noggrant. Om din experimentella funktion måste innehålla ändringar i MRTK-kärnkoden bör du överväga att dela upp MRTK-ändringar i en separat pull-begäran som innehåller tester och dokumentation.

Användning av din experimentella funktion bör inte påverka människors möjlighet att använda kärnkontroller

De flesta använder grundläggande UX-komponenter som knappen, ManipulationHandler och Interactable mycket ofta. De kommer förmodligen inte att använda din experimentella funktion om den hindrar dem från att använda knappar.

Om du använder komponenten får du inte bryt knappar, ManipulationHandler, BoundingBox eller interagera.

I denna ScrollableObjectCollection PR gjorde till exempel tillägg av en ScrollableObjectCollection att personer inte kunde använda HoloLens-knappens prefabs. Även om detta inte orsakades av en bugg i pull-begäran (utan snarare exponerade ett befintligt fel), förhindrade det PR från att checkas in.

Ange en exempelscen som visar hur du använder funktionen

Personer behöver se hur du använder din funktion och hur du testar den.

Ange ett exempel under MRTK/Examples/Experimental/YOUR_FEATURE

Minimera användar synliga brister i experimentella funktioner

Andra kommer inte att använda den experimentella funktionen om den inte fungerar, den kommer inte att uppgraderas till en funktion.

Testa exempelscenen på målplattformen och se till att den fungerar som förväntat. Se till att din funktion också fungerar i redigeringsprogrammet, så att användarna snabbt kan iterera och se din funktion även om de inte har målplattformen.

Ta examen från experimentell kod till MRTK-kod

Om en funktion får ganska mycket användning bör vi uppgradera den till kärn-MRTK-kod. För att göra detta bör funktionen ha tester, dokumentation och en exempelscen.

När du är redo att ta examen från funktionen MRTK skapar du ett problem att checka in din pull-begäran mot. Pr bör innehålla allt som behövs för att göra detta till en grundläggande funktion: tester, dokumentation och en exempelscen som visar användning.

Glöm inte heller att uppdatera namnrymderna för att ta bort underområdet "Experimentell".