Fonctionnalités expérimentales — MRTK2

Certaines fonctionnalités sur lesquelles travaille l’équipe MRTK semblent avoir une grande valeur initiale, même si nous n’en avons pas encore complètement défini les détails. Pour ces types de fonctionnalités, nous voulons que la communauté ait une chance de les découvrir précocement. Parce qu’ils sont en début du cycle, nous les qualifions d’expérimentaux pour indiquer qu’ils sont encore en cours d’évolution et sont susceptibles de changer au fil du temps.

À quoi s’attendre d’une fonctionnalité expérimentale

Si un composant est marqué expérimental, vous pouvez vous attendre à ce qui suit :

• Exemple de scène illustrant l’utilisation, situé sous MRTK/Examples/Experimental le sous-dossier
• Les fonctionnalités expérimentales peuvent ne pas avoir de documentation.
• Ils n’ont probablement pas de tests.
• Les fonctionnalités expérimentales sont susceptibles de changer.

Instructions relatives aux fonctionnalités expérimentales

Le code expérimental doit se trouver dans un dossier distinct

Le code expérimental doit être inséré dans un dossier expérimental de niveau supérieur suivi du nom de la fonctionnalité expérimentale. Par exemple, si vous essayez de contribuer à une nouvelle fonctionnalité FooBar, placez du code dans les éléments suivants :

• Exemples de scènes, les scripts entrent dans MRTK/Examples/Experimental/FooBar/
• Scripts de composant, préfabriqués vont dans MRTK/SDK/Experimental/FooBar/
• Les inspecteurs de composants entrent dans MRTK/SDK/Inspectors/Experimental/FooBar

Lorsque vous utilisez des sous-dossiers sous le nom de la fonctionnalité expérimentale, essayez de miroir la même structure de dossiers de MRTK.

Par exemple, les solveurs passeraient sous MRTK/SDK/Experimental/FooBar/Features/Utilities/Solvers/FooBarSolver.cs

Conservez les scènes d’un dossier de scène près du haut : MRTK/Examples/Experimental/FooBar/Scenes/FooBarExample.unity

Notes

Nous avons envisagé de ne pas avoir un seul dossier racine expérimental et à la place de placer Experimental sous disons MRTK/Examples/HandTracking/Scenes/Experimental/HandBasedMenuExample.unity. Nous avons décidé d’utiliser les dossiers à la base pour faciliter la découverte des fonctionnalités expérimentales.

Le code expérimental doit se trouver dans un espace de noms spécial

Assurez-vous que le code expérimental réside dans un espace de noms expérimental qui correspond à l’emplacement non expérimental. Par exemple, si votre composant fait partie des solveurs sur Microsoft.MixedReality.Toolkit.Utilities.Solvers, son espace de noms doit être Microsoft.MixedReality.Toolkit.Experimental.Utilities.Solvers.

Pour obtenir un exemple, consultez cette demande de tirage .

Les fonctionnalités expérimentales doivent avoir un attribut [Expérimental]

Ajoutez un [Experimental] attribut au-dessus de l’un de vos champs pour qu’une petite boîte de dialogue s’affiche dans l’éditeur de composant qui mentionne que votre fonctionnalité est expérimentale et soumise à des modifications importantes.

Les menus pour les fonctionnalités expérimentales doivent passer sous le sous-menu « Expérimental »

Vérifiez que les fonctionnalités expérimentales se trouvent sous les sous-menus « expérimentaux » lors de l’ajout de commandes aux menus dans l’éditeur. Voici quelques exemples :

Ajout d’une commande de menu de niveau supérieur :

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

Ajout d’un menu de composant :

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

Documentation

Suivez ces étapes pour ajouter de la documentation pour votre fonctionnalité expérimentale :

1. Toute documentation relative à une fonctionnalité expérimentale doit figurer dans un readme.md fichier dans le dossier expérimental. Par exemple, MRTK/SDK/Experimental/PulseShader/readme.md.

2. Sous Vue d’ensemble des fonctionnalités , ajoutez un lien dans la section Expérimental à l’adresse Documentation/toc.yml.

Réduire l’impact sur le code MRTK

Bien que votre modification MRTK puisse faire fonctionner votre expérience, elle pourrait avoir un impact sur d’autres personnes d’une manière que vous n’attendez pas. Toutes les régressions que vous effectuez sur le code principal MRTK entraînent le rétablissement de votre demande de tirage.

Visez à n’avoir aucune modification dans les dossiers autres que les dossiers expérimentaux. Voici une liste de dossiers qui peuvent avoir des modifications expérimentales :

• MRTK/SDK/Expérimental
• MRTK/SDK/Inspectors/Experimental
• MRTK/Examples/Experimental

Les modifications en dehors de ces dossiers doivent être traitées avec beaucoup de soin. Si votre fonctionnalité expérimentale doit inclure des modifications apportées au code principal MRTK, envisagez de fractionner les modifications MRTK en une demande de tirage distincte qui comprend des tests et de la documentation.

L’utilisation de votre fonctionnalité expérimentale ne doit pas avoir d’impact sur la capacité des utilisateurs à utiliser des contrôles de base

La plupart des gens utilisent très fréquemment les principaux composants d’expérience utilisateur tels que le bouton, ManipulationHandler et Interactable. Ils n’utiliseront probablement pas votre fonctionnalité expérimentale si elle les empêche d’utiliser des boutons.

L’utilisation de votre composant ne doit pas interrompre les boutons, ManipulationHandler, BoundingBox ou interactable.

Par exemple, dans cette demande de tirage ScrollableObjectCollection, l’ajout d’un ScrollableObjectCollection a entraîné l’impossibilité d’utiliser les préfabriqués du bouton HoloLens. Même si cela n’a pas été dû à un bogue dans la demande de tirage (mais plutôt à un bogue existant), cela a empêché la demande de tirage d’être enregistrée.

Fournir un exemple de scène qui montre comment utiliser la fonctionnalité

Personnes devez voir comment utiliser votre fonctionnalité et comment la tester.

Fournissez un exemple sous MRTK/Examples/Experimental/YOUR_FEATURE

Réduire les défauts visibles par l’utilisateur dans les fonctionnalités expérimentales

D’autres n’utiliseront pas la fonctionnalité expérimentale si elle ne fonctionne pas, elle ne passera pas à une fonctionnalité.

Testez votre exemple de scène sur votre plateforme cible, vérifiez qu’elle fonctionne comme prévu. Assurez-vous que votre fonctionnalité fonctionne également dans l’éditeur, afin que les utilisateurs puissent rapidement itérer et voir votre fonctionnalité même s’ils ne disposent pas de la plateforme cible.

Obtention d’un code expérimental dans du code MRTK

Si une fonctionnalité finit par voir beaucoup d’utilisation, nous devons la transformer en code MRTK de base. Pour ce faire, la fonctionnalité doit avoir des tests, de la documentation et un exemple de scène.

Lorsque vous êtes prêt à graduer la fonctionnalité MRTK, créez un problème à case activée dans votre demande de tirage. La demande de tirage doit inclure tous les éléments nécessaires pour en faire une fonctionnalité de base : tests, documentation et un exemple de scène montrant l’utilisation.

N’oubliez pas non plus de mettre à jour les espaces de noms pour supprimer le sous-espace « Expérimental ».