Fonctionnalités expérimentales — MRTK2

Certaines fonctionnalités que l’équipe MRTK travaille semblent avoir beaucoup de valeur initiale, même si nous n’avons pas entièrement étoffé les détails. Pour ces types de fonctionnalités, nous voulons que la communauté obtienne une chance de les voir tôt. Étant donné qu’elles sont au début du cycle, nous les étiqueter comme expérimentales pour indiquer qu’elles évoluent toujours et qu’elles sont susceptibles de changer au fil du temps.

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

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

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

Recommandations relatives aux fonctionnalités expérimentales

Le code expérimental doit résider dans un dossier distinct

Le code expérimental doit accéder à 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 vont 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 d’miroir la même structure de dossiers que MRTK.

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

Conservez les scènes dans un dossier de scène près de la partie supérieure : MRTK/Examples/Experimental/FooBar/Scenes/FooBarExample.unity

Remarque

Nous avons envisagé de ne pas avoir un seul dossier racine expérimental et de placer à la place Experimental sous disons MRTK/Examples/HandTracking/Scenes/Experimental/HandBasedMenuExample.unity. Nous avons décidé d’utiliser des 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

Vérifiez que le code expérimental se trouve 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.

Consultez cette demande de tirage pour obtenir un exemple.

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 sujette à des modifications importantes.

Les menus des 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 la documentation de votre fonctionnalité expérimentale :

1. Toute documentation relative à une fonctionnalité expérimentale doit être 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 peut 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 la restauration 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 du code principal MRTK, envisagez de fractionner les modifications MRTK en une demande de tirage distincte qui inclut 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 les contrôles de base

La plupart des gens utilisent très fréquemment des composants d’expérience utilisateur de base 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 interagir.

Par exemple, dans cette demande de tirage ScrollableObjectCollection, l’ajout d’un ScrollableObjectCollection empêchait les utilisateurs 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 a plutôt exposé un bogue existant), cela a empêché la demande de tirage d’être archivée.

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

Personnes avez besoin de 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’utilisent 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 n’ont pas la plateforme cible.

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

Si une fonctionnalité finit par être utilisée beaucoup, nous devrions la graduer en code MRTK de base. Pour ce faire, la fonctionnalité doit avoir des tests, une 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 : des tests, de la 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 ».