Contribución a MRTK3

MRTK3 es un proyecto de código abierto publicado 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 sencillo. Se recomienda usar el proyecto de MRTKDevTemplate Unity como un práctico equipo 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 sobre el proyecto MRTKDevTemplate para obtener más detalles sobre las escenas de ejemplo y las dependencias locales en el disco.

Guía de contribución

1. Bifurque el repositorio de MRTK a su cuenta de GitHub.

2. Clone el repositorio de MRTK bifurcado siguiendo nuestra guía sobre el inicio a partir 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 correcta, 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 plantilla MRTKDevTemplate ubicado en UnityProjects/MRTKDevTemplate. Puede agregar el proyecto a Unity Hub para facilitar el acceso.

5. Realice los cambios que desee y cree pruebas unitarias que garanticen que los cambios funcionan según lo previsto. Asegúrese de realizar las pruebas en el editor e impleméntelas en el dispositivo. Confirme los cambios realizados en la rama. Publique la rama en la bifurcación ascendente.

6. Abra una solicitud de incorporación de cambios en el repositorio de MRTK que tenga como destino la rama mrtk3. Asegúrese de describir con precisión los cambios realizados y aplicar etiquetas relevantes a la solicitud de incorporación de cambios para una mejor categorización y evaluación de prioridades. 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 para garantizar que MRTK es una base confiable para aplicaciones de realidad mixta de alta calidad. Las nuevas características que se agregan deben tener pruebas unitarias para garantizar que su funcionalidad siga siendo correcta a medida que se realicen 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 mano, la mirada, la posición de HMD y otras características básicas relacionadas con la entrada. A continuación, se incluyen algunos consejos generales para escribir pruebas unitarias apropiadas:

• Intente escribir pruebas más pormenorizadas 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 responsables del mantenimiento ver qué característica específica se ha dañado. También se aprecian más pruebas generales de funcionalidad de un extremo a otro, pero asegúrese de que cada parte más pequeña de la característica esté bien probada para comenzar.
• Asegúrese de que la prueba (y la característica) no realice ninguna suposición sobre la orientación o la ubicación del usuario. Las pruebas y características deben funcionar en cualquier rotación o desplazamiento arbitrario a partir del origen del mundo.
• Si las pruebas simulan la entrada del usuario, asegúrese de incluir BaseRuntimeInputTests como subclase, lo que garantiza que el agente de prueba adecuado esté configurado y desmontado.
• 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 no se registran las interacciones.
• 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.json y 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. También se ejecutan otros trabajos de integración continua (CI) en la confirmación resultante en la rama de desarrollo principal para garantizar que los paquetes dañados no se implementen en la fuente.

Si las pruebas superan la fase del editor pero no la ejecución de CI, debe ejecutarlas localmente en el modo por lotes. Algunos tipos de pruebas pueden producir errores inesperados al ejecutarse en el modo por lotes sin gráficos debido a diferencias de tiempo u otras peculiaridades de Unity. Ejecutar las pruebas localmente en el modo por lotes ayuda a identificar estas pruebas incoherentes antes de que lo haga la CI.

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

$ ./Tooling/Tests/run_playmode_tests.ps1

El script generará archivos de salida en la carpeta /out, incluidos los archivos .log y el archivo .xml de resultados de la prueba. Para filtrar las pruebas que se ejecutan, pase una expresión regular al script. También se pueden proporcionar ubicaciones de carpetas de proyecto y versiones personalizadas de Unity como argumentos.

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