Experimentele functies — MRTK2

Sommige functies waaraan het MRTK-team werkt, lijken veel beginwaarde te hebben, zelfs als we de details nog niet volledig hebben uitgewerkt. Voor dit type functies willen we dat de community de kans krijgt om ze in een vroeg stadium te zien. Omdat ze zich in het begin van de cyclus bevinden, labelen we ze als experimenteel om aan te geven dat ze nog steeds in ontwikkeling zijn en in de loop van de tijd kunnen worden gewijzigd.

Wat u kunt verwachten van een experimentele functie

Als een onderdeel is gemarkeerd als experimenteel, kunt u het volgende verwachten:

• Een voorbeeldscène waarin het gebruik wordt gedemonstreerd, onder MRTK/Examples/Experimental de submap
• Experimentele functies hebben mogelijk geen documenten.
• Ze hebben waarschijnlijk geen tests.
• Experimentele functies kunnen worden gewijzigd.

Richtlijnen voor experimentele functies

Experimentele code moet zich in een afzonderlijke map bevinden

Experimentele code moet naar een experimentele map op het hoogste niveau gaan, gevolgd door de naam van de experimentele functie. Als u bijvoorbeeld probeert bij te dragen aan een nieuwe functie FooBar, plaatst u code in het volgende:

• Voorbeeldscènes, scripts gaan naar MRTK/Examples/Experimental/FooBar/
• Onderdeelscripts, prefabs gaan naar MRTK/SDK/Experimental/FooBar/
• Component inspectors gaan naar MRTK/SDK/Inspectors/Experimental/FooBar

Wanneer u submappen gebruikt onder de naam van de experimentele functie, probeert u dezelfde mapstructuur van MRTK te spiegelen.

Oplossers gaan bijvoorbeeld onder MRTK/SDK/Experimental/FooBar/Features/Utilities/Solvers/FooBarSolver.cs

Scènes bewaren in een scènemap bovenaan: MRTK/Examples/Experimental/FooBar/Scenes/FooBarExample.unity

Notitie

We hebben overwogen om niet één experimentele hoofdmap te hebben en in plaats daarvan experimenteel te plaatsen onder bijvoorbeeld MRTK/Examples/HandTracking/Scenes/Experimental/HandBasedMenuExample.unity. We hebben besloten om mappen aan de basis te gebruiken om de experimentele functies gemakkelijker te ontdekken.

Experimentele code moet zich in een speciale naamruimte bevinden

Zorg ervoor dat de experimentele code zich in een experimentele naamruimte bevindt die overeenkomt met de niet-experimentele locatie. Als uw onderdeel bijvoorbeeld deel uitmaakt van oplossers op Microsoft.MixedReality.Toolkit.Utilities.Solvers, moet de naamruimte zijn Microsoft.MixedReality.Toolkit.Experimental.Utilities.Solvers.

Zie deze pull-aanvraag voor een voorbeeld.

Experimentele functies moeten het kenmerk [Experimenteel] hebben

Voeg een [Experimental] kenmerk toe boven een van uw velden om een klein dialoogvenster weer te geven in de onderdeeleditor waarin wordt vermeld dat uw functie experimenteel is en onderhevig is aan belangrijke wijzigingen.

Menu's voor experimentele functies moeten onder het submenu Experimenteel worden weergegeven

Zorg ervoor dat experimentele functies zich onder 'experimentele' submenu's bevinden wanneer u opdrachten toevoegt aan menu's in de editor. Enkele voorbeelden:

Een menuopdracht op het hoogste niveau toevoegen:

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

Een onderdeelmenu toevoegen:

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

Documentatie

Volg deze stappen om documentatie toe te voegen voor uw experimentele functie:

1. Alle documentatie voor een experimentele functie moet in een readme.md bestand in de experimentele map worden geplaatst. Bijvoorbeeld MRTK/SDK/Experimental/PulseShader/readme.md.

2. Voeg onder Functieoverzichten een koppeling toe in de sectie Experimenteel op Documentation/toc.yml.

De impact op MRTK-code minimaliseren

Hoewel uw MRTK-wijziging ervoor kan zorgen dat uw experiment werkt, kan dit gevolgen hebben voor andere personen op een manier die u niet verwacht. Elke regressies die u naar de MRTK-kerncode maakt, leidt ertoe dat uw pull-aanvraag wordt teruggedraaid.

Streven naar nul wijzigingen in andere mappen dan experimentele mappen. Hier volgt een lijst met mappen die experimentele wijzigingen kunnen hebben:

• MRTK/SDK/Experimental
• MRTK/SDK/Inspectors/Experimental
• MRTK/Voorbeelden/Experimenteel

Wijzigingen buiten deze mappen moeten zeer zorgvuldig worden behandeld. Als uw experimentele functie wijzigingen in MRTK-kerncode moet bevatten, kunt u mrtk-wijzigingen opsplitsen in een afzonderlijke pull-aanvraag die tests en documentatie bevat.

Het gebruik van uw experimentele functie mag geen invloed hebben op de mogelijkheid van personen om kernbesturingselementen te gebruiken

De meeste mensen gebruiken vaak belangrijke UX-onderdelen, zoals de knop, ManipulationHandler en Interactable. Ze gebruiken waarschijnlijk uw experimentele functie niet als deze verhindert dat ze knoppen gebruiken.

Het gebruik van uw onderdeel mag knoppen, ManipulationHandler, BoundingBox of interactie niet verbreken.

In deze Pull-aanvraag voor ScrollableObjectCollection heeft het toevoegen van een ScrollableObjectCollection ervoor gezorgd dat mensen de holoLens-knopprefabs niet konden gebruiken. Hoewel dit niet is veroorzaakt door een fout in de pull-aanvraag (maar eerder een bestaande fout heeft blootgelegd), kon de pull-aanvraag niet worden ingecheckt.

Geef een voorbeeldscène op die laat zien hoe u de functie gebruikt

Mensen wilt weten hoe u uw functie gebruikt en hoe u deze kunt testen.

Geef een voorbeeld op onder MRTK/Examples/Experimental/YOUR_FEATURE

Zichtbare fouten van gebruikers in experimentele functies minimaliseren

Anderen zullen de experimentele functie niet gebruiken als deze niet werkt, het zal niet worden aangepast aan een functie.

Test uw voorbeeldscène op uw doelplatform en zorg ervoor dat deze werkt zoals verwacht. Zorg ervoor dat uw functie ook werkt in de editor, zodat mensen uw functie snel kunnen herhalen en zien, zelfs als ze het doelplatform niet hebben.

Experimentele code in MRTK-code voltooien

Als een functie uiteindelijk behoorlijk veel wordt gebruikt, moeten we deze in de kern-MRTK-code instellen. Hiervoor moet de functie tests, documentatie en een voorbeeldscène hebben.

Wanneer u klaar bent om de functie MRTK af te studeren, maakt u een probleem waarmee u uw pull-aanvraag kunt controleren. De pull-aanvraag moet alle dingen bevatten die nodig zijn om hiervan een kernfunctie te maken: tests, documentatie en een voorbeeldscène met gebruik.

Vergeet ook niet om de naamruimten bij te werken om de subruimte 'Experimenteel' te verwijderen.