Contribución a MRTK3

MRTK3 es un proyecto de código abierto bajo la licencia MIT. Las contribuciones de la comunidad son bienvenidas y apreciadas, tanto para nuevas características como para correcciones de errores.

Contribuir a MRTK3 es fácil. Se recomienda usar el proyecto de MRTKDevTemplate Unity como una cómoda plataforma de pruebas de desarrollo, ya que ya incluye todos los paquetes MRTK3 como dependencias locales en disco. Para obtener más información, consulte la documentación del proyecto MRTKDevTemplate para obtener más información sobre las escenas de ejemplo y las dependencias locales en disco.

Guía de contribución

1. Bifurcar el repositorio MRTK en la cuenta de GitHub.

2. Clone el repositorio de MRTK bifurcado siguiendo nuestra guía sobre el inicio de un proyecto de plantilla Asegúrese de que tiene las herramientas necesarias, especialmente la versión correcta de Unity. Para asegurarse de que se encuentra en la rama derecha, clone mediante el comando :

git clone --branch mrtk3 YOUR_GIT_URL

3. Cree una nueva rama para los cambios o correcciones.

git checkout -b yourchange_fix

4. Abra el proyecto de MRTKDevTemplate plantilla ubicado en UnityProjects/MRTKDevTemplate. Puede agregar el proyecto a Unity Hub para facilitar el acceso.

5. Realice los cambios deseados y cree pruebas unitarias que garanticen que los cambios funcionen según lo esperado. Asegúrese de probar en el editor e implementado en el dispositivo. Confirme los cambios en la rama. Publique la rama en la bifurcación ascendente.

6. Abra una solicitud de incorporación de cambios en el repositorio MRTK, destinada a la mrtk3 rama. Asegúrese de describir con precisión los cambios que ha realizado y de aplicar las etiquetas pertinentes a la solicitud de incorporación de cambios para una mejor categorización y clasificación. Si es un nuevo colaborador de MRTK, es posible que tenga que firmar nuestro contrato de contribución.

7. Solucione las correcciones solicitadas por la comunidad o el equipo de mantenimiento y combine la solicitud de incorporación de cambios después de la aprobación.

Escritura de pruebas

Las pruebas son una parte fundamental de garantizar que MRTK es una base confiable para aplicaciones de realidad mixta de alta calidad. Las nuevas características que se agreguen deben tener pruebas unitarias para asegurarse de que su funcionalidad sigue siendo correcta a medida que se realizan otros cambios en el código base en el futuro.

Para escribir pruebas unitarias, se recomienda examinar primero las pruebas unitarias existentes y aprender cómo se usan las utilidades de prueba y el simulador de MRTK para simular la entrada XR. Puede simular la entrada de la mano, la mirada, la posición HMD y otras características básicas relacionadas con la entrada. Estos son algunos consejos generales para escribir buenas pruebas unitarias:

• Intente escribir pruebas más granulares que evalúen partes más pequeñas de la funcionalidad, en lugar de pruebas monolíticas más grandes. Las pruebas unitarias más pormenorizadas permiten a los mantenedores ver qué característica específica se ha roto. También se aprecian pruebas de funcionalidad más generales de un extremo a otro, pero asegúrese de que cada parte más pequeña de la característica esté bien probada para empezar.
• Asegúrese de que la prueba (y la característica) no hacen ninguna suposición sobre la orientación o la ubicación del usuario. Las pruebas y características deben funcionar en cualquier desplazamiento o rotación arbitrario desde el origen del mundo.
• Si prueba la entrada del usuario ficticio, asegúrese de subclase de , BaseRuntimeInputTestslo que garantiza que el arnés de prueba adecuado esté configurado y desgarrado.
• Use la parametrización de NUnit para aumentar fácilmente la variedad y flexibilidad de la prueba. Consulte la documentación de las pruebas de NUnit parametrizadas aquí.
• Algunas entradas o interacciones pueden tardar varios fotogramas en registrarse. Puede usar yield return RuntimeTestUtilities.WaitForUpdates() para agregar fotogramas adicionales de retraso a la prueba si las interacciones no se registran.
• Intente escribir pruebas unitarias que se ejecuten lo antes posible para evitar tiempos de iteración de CI lentos.
• Asegúrese de agregar las dependencias de prueba pertinentes a package.jsony las referencias correctas al archivo de definición de ensamblado de la carpeta de prueba.

Integración continua

Cada solicitud de incorporación de cambios está sujeta a pruebas automatizadas antes de poder combinarse. Otros trabajos de integración continua (CI) también se ejecutan en la confirmación resultante en la rama de desarrollo principal para asegurarse de que los paquetes rotos no se implementan en la fuente.

Si las pruebas pasan en el editor pero producen un error en la ejecución de CI, debe ejecutar las pruebas localmente en modo por lotes. Algunos tipos de pruebas pueden producir un error inesperado al ejecutarse en modo por lotes sin gráficos debido a diferencias de tiempo u otras peculiaridades de Unity. La ejecución de las pruebas localmente en modo por lotes ayuda a identificar estas pruebas incoherentes antes de que la CI lo haga.

Use el Tooling/Tests/run_playmode_tests.ps1 script para ejecutar pruebas localmente en modo por lotes. Para ello, deberá cerrar el editor de Unity.

$ ./Tooling/Tests/run_playmode_tests.ps1

El script generará archivos de salida en la /out carpeta, incluidos los .log archivos y los resultados .xmlde la prueba. Puede filtrar qué pruebas se ejecutan pasando una expresión regular al script. Las versiones personalizadas de Unity y las ubicaciones de carpetas del proyecto también se pueden proporcionar como argumentos.

$ ./Tooling/Tests/run_playmode_tests.ps1 -unityVersion 2021.3.5f1 -projectPath ../my/project/path