Experimentella funktioner

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

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 demonstrerar användning, som finns MRTK/Examples/Experimental under undermappen
  • Experimentella funktioner kanske inte har dokument.
  • De har förmodligen inte några 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å toppnivå följt av namnet på den experimentella funktionen. Om du till exempel försöker bidra med en ny funktion FooBar lägger du till kod i följande:

  • Exempelscener, skript går in i MRTK/Examples/Experimental/FooBar/
  • Komponentskript, prefab-komponenter går in i MRTK/SDK/Experimental/FooBar/
  • Komponentkontrollerna går in på MRTK/SDK/Inspectors/Experimental/FooBar

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

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

Förvara 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 utan i stället placera Experimentell under säg MRTK/Examples/HandTracking/Scenes/Experimental/HandBasedMenuExample.unity . Vi har bestämt oss för att använda mappar vid basen för att göra det enklare att identifiera experimentella funktioner.

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 komponenten till exempel är en del av lösare på Microsoft.MixedReality.Toolkit.Utilities.Solvers ska dess namnområde vara Microsoft.MixedReality.Toolkit.Experimental.Utilities.Solvers .

Ett exempel finns i den här pr-frågan.

Experimentella funktioner bör ha attributet [Experimental]

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

Se till att experimentella funktioner är 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 ExperimentellDocumentation/toc.yml .

Minimera påverkan på MRTK-kod

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

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 den experimentella funktionen 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 viktiga UX-komponenter som knappen, ManipulationHandler och Interactable mycket ofta. De kommer troligen inte att använda din experimentella funktion om den förhindrar att de använder knappar.

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

I den här ScrollableObjectCollection PRorsakade tillägg av en ScrollableObjectCollection att personer inte kunde använda prefab-HoloLens-knappen. Även om detta inte orsakades av ett fel i PR (utan snarare exponerade en befintlig bugg) förhindrade det att PR checkades in.

Ge ett exempel på en scen som visar hur du använder funktionen

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

Ge ett exempel under MRTK/Examples/Experimental/YOUR_FEATURE

Minimera användar synliga brister i experimentella funktioner

Andra använder inte den experimentella funktionen om den inte fungerar, den uppgraderas inte till en funktion.

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

Graduering av experimentell kod i MRTK-kod

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

När du är redo att uppgradera funktionen MRTK skapar du ett ärende att checka in din PR 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".