Características experimentales: MRTK2

Algunas características en las que el equipo de MRTK trabaja parecen tener un gran valor inicial, incluso si no se han detallado completamente los detalles. Queremos que la comunidad tenga la oportunidad de ver pronto estos tipos de características. Dado que están al principio del ciclo, las etiquetamos como experimentales para indicar que siguen evolucionando y están sujetas a cambios a lo largo del tiempo.

Qué esperar de una característica experimental

Si un componente está marcado como experimental, puede esperar lo siguiente:

• Una escena de ejemplo que muestra el uso, que se encuentra en MRTK/Examples/Experimental la subcarpeta
• Es posible que las características experimentales no tengan documentación.
• Probablemente no tengan pruebas.
• Las características experimentales están sujetas a cambios.

Directrices de características experimentales

El código experimental debe residir en una carpeta independiente

El código experimental debe ir a una carpeta experimental de nivel superior seguida del nombre de la característica experimental. Por ejemplo, si intenta contribuir a una nueva característica FooBar, coloque código en lo siguiente:

• Escenas de ejemplo, los scripts entran en MRTK/Examples/Experimental/FooBar/
• Scripts de componentes y objetos prefabricados entran en MRTK/SDK/Experimental/FooBar/
• Los inspectores de componentes entran en MRTK/SDK/Inspectors/Experimental/FooBar

Al usar subcarpetas en el nombre de la característica experimental, intente reflejar la misma estructura de carpetas de MRTK.

Por ejemplo, los solucionadores estarían en MRTK/SDK/Experimental/FooBar/Features/Utilities/Solvers/FooBarSolver.cs

Mantenga las escenas en una carpeta de escena cerca de la parte superior: MRTK/Examples/Experimental/FooBar/Scenes/FooBarExample.unity

Nota:

Hemos considerado que no tiene una sola carpeta raíz experimental y, en su lugar, se coloca Experimental en .MRTK/Examples/HandTracking/Scenes/Experimental/HandBasedMenuExample.unity Decidimos ir con carpetas en la base para facilitar la detección de las características experimentales.

El código experimental debe estar en un espacio de nombres especial.

Asegúrese de que el código experimental reside en un espacio de nombres experimental que coincida con la ubicación no experimental. Por ejemplo, si el componente forma parte de solucionadores en Microsoft.MixedReality.Toolkit.Utilities.Solvers, su espacio de nombres debe ser Microsoft.MixedReality.Toolkit.Experimental.Utilities.Solvers.

Consulte esta solicitud de incorporación de cambios para obtener un ejemplo.

Las características experimentales deben tener un atributo [Experimental]

Agregue un [Experimental] atributo encima de uno de los campos para que aparezca un cuadro de diálogo pequeño en el editor de componentes que mencione que la característica es experimental y está sujeta a cambios significativos.

Los menús de las características experimentales deben ir en el submenú "Experimental"

Asegúrese de que las características experimentales se encuentran en submenúes "experimentales" al agregar comandos a menús en el editor. Estos son algunos ejemplos:

Agregar un comando de menú de nivel superior:

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

Agregar un menú de componentes:

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

Documentación

Siga estos pasos para agregar documentación para la característica experimental:

1. Cualquier documentación de una característica experimental debe ir en un readme.md archivo de la carpeta experimental. Por ejemplo, MRTK/SDK/Experimental/PulseShader/readme.md.

2. En Información general de características , agregue un vínculo en la sección Experimental de Documentation/toc.yml.

Minimizar el impacto en el código MRTK

Aunque el cambio de MRTK podría hacer que el experimento funcione, podría afectar a otras personas de maneras que no espera. Cualquier regresión que realice en el código principal de MRTK provocaría que la solicitud de incorporación de cambios se revierta.

El objetivo es tener cero cambios en las carpetas distintas de las carpetas experimentales. Esta es una lista de carpetas que pueden tener cambios experimentales:

• MRTK/SDK/Experimental
• MRTK/SDK/Inspectors/Experimental
• MRTK/Examples/Experimental

Los cambios fuera de estas carpetas se deben tratar con mucho cuidado. Si la característica experimental debe incluir cambios en el código principal de MRTK, considere la posibilidad de dividir los cambios de MRTK en una solicitud de incorporación de cambios independiente que incluya pruebas y documentación.

El uso de la característica experimental no debería afectar a la capacidad de los usuarios para usar controles principales

La mayoría de las personas usan componentes básicos de la experiencia de usuario, como el botón, ManipulationHandler e Interactable con mucha frecuencia. Es probable que no usen la característica experimental si impide que usen botones.

El uso del componente no debe interrumpir los botones, ManipulationHandler, BoundingBox ni interactuar.

Por ejemplo, en esta solicitud de incorporación de cambios ScrollableObjectCollection, agregar un ScrollableObjectCollection provocó que las personas no pudieran usar los objetos prefabricados de botón de HoloLens. Aunque esto no se debe a un error en la solicitud de incorporación de cambios (sino que se ha expuesto un error existente), impedía que la solicitud de incorporación de cambios se comprobara.

Proporcionar una escena de ejemplo que muestra cómo usar la característica

Personas necesita ver cómo usar la característica y cómo probarla.

Proporcione un ejemplo en MRTK/Examples/Experimental/YOUR_FEATURE

Minimizar los errores visibles del usuario en las características experimentales

Otros no usarán la característica experimental si no funciona, no se graduará en una característica.

Pruebe la escena de ejemplo en la plataforma de destino y asegúrese de que funciona según lo previsto. Asegúrese de que la característica también funciona en el editor, por lo que los usuarios pueden iterar rápidamente y ver la característica incluso si no tienen la plataforma de destino.

Graduación del código experimental en código MRTK

Si una característica termina viendo mucho uso, deberíamos graduarla en el código MRTK principal. Para ello, la característica debe tener pruebas, documentación y una escena de ejemplo.

Cuando esté listo para graduar la característica MRTK, cree un problema para proteger la solicitud de incorporación de cambios. La solicitud de incorporación de cambios debe incluir todas las cosas necesarias para que esta sea una característica principal: pruebas, documentación y una escena de ejemplo que muestra el uso.

Además, no olvide actualizar los espacios de nombres para quitar el subespacio "Experimental".