Experimentele functies

Sommige functies waar het MRTK-team aan werkt, lijken veel aanvankelijke waarde te hebben, zelfs als we de details nog niet volledig hebben uitwerkt. Voor dit soort functies willen we dat de community deze in een vroeg stadium kan zien. Omdat ze vroeg in de cyclus zijn, labelen we ze als experimenteel om aan te geven dat ze nog steeds in ontwikkeling zijn en in de tijd onderhevig zijn aan veranderingen.

Wat u kunt verwachten van een experimentele functie

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

  • Een voorbeeldscène waarin het gebruik wordt gedemonstreert, dat zich onder MRTK/Examples/Experimental de submap bevindt
  • 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

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

  • Voorbeeldscènes, scripts gaan in MRTK/Examples/Experimental/FooBar/
  • Onderdeelscripts, prefabs gaan naar MRTK/SDK/Experimental/FooBar/
  • Onderdeelinspecteurs 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.

Zo zouden oplossers onder gaan MRTK/SDK/Experimental/FooBar/Features/Utilities/Solvers/FooBarSolver.cs

Plaats scènes 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 onder de naam te MRTK/Examples/HandTracking/Scenes/Experimental/HandBasedMenuExample.unity plaatsen. We hebben besloten om de basismappen te gebruiken om de experimentele functies gemakkelijker te ontdekken.

Experimentele code moet zich in een speciale naamruimte

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 , moet Microsoft.MixedReality.Toolkit.Utilities.Solvers de naamruimte Microsoft.MixedReality.Toolkit.Experimental.Utilities.Solvers zijn.

Zie deze pr voor een voorbeeld.

Experimentele functies moeten een kenmerk [Experimenteel] hebben

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

Zorg ervoor dat experimentele functies onder 'experimentele' submenu's staan 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 voor uw experimentele functie toe te voegen:

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

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

Impact op MRTK-code minimaliseren

Hoewel uw MRTK-wijziging uw experiment mogelijk aan het werk kan krijgen, kan dit van invloed zijn op andere mensen op een manier die u niet verwacht. Als u regressies naar de MRTK-kerncode maakt, wordt uw pull-aanvraag teruggedraaid.

Richt u op nul wijzigingen in andere mappen dan experimentele mappen. Hier ziet u een lijst met mappen die experimentele wijzigingen kunnen hebben:

  • MRTK/SDK/experimenteel
  • MRTK/SDK/Inspectors/Experimenteel
  • MRTK/Examples/Experimental

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

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

De meeste mensen gebruiken zeer vaak kernonderdelen van UX, zoals de knop ManipulationHandler en Interactable. Ze gebruiken waarschijnlijk uw experimentele functie niet als deze voorkomt dat ze knoppen gebruiken.

Het gebruik van uw onderdeel mag knoppen, ManipulationHandler, BoundingBox of interactable niet breken.

In deze Pr van ScrollableObjectCollectionhebben gebruikers bijvoorbeeld door het toevoegen van een ScrollableObjectCollection de knop prefabs HoloLens gebruiken. Hoewel dit niet werd veroorzaakt door een fout in de pr (maar een bestaande fout aan het licht is gebracht), werd voorkomen dat de pr werd ingecheckt.

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

Mensen moeten zien hoe ze uw functie kunnen gebruiken en hoe ze deze kunnen testen.

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

Zichtbare fouten van gebruikers in experimentele functies minimaliseren

Andere gebruiken de experimentele functie niet als deze niet werkt, maar worden niet over tot 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 itereren en zien, zelfs als ze het doelplatform niet hebben.

Experimentele code in MRTK-code onderverwerkt

Als een functie uiteindelijk heel veel gebruik gaat zien, moeten we deze in de MRTK-kerncode gaan gebruiken. Hiervoor moet de functie tests, documentatie en een voorbeeldscène hebben.

Wanneer u klaar bent om de functie MRTK te gaan gebruiken, maakt u een probleem waarmee u uw pr kunt controleren. De pr moet alle dingen bevatten die nodig zijn om hiervan een kernfunctie te maken: tests, documentatie en een voorbeeldscène waarin het gebruik wordt weergegeven.

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