Solicitudes de incorporación de cambiosPull requests

Requisitos previosPrerequisites

Si no ha contribuido a ningún proyecto de Microsoft antes, es posible que se le pida que firme un contrato de licencia de contribución.If you haven't contributed to a Microsoft project before, you may be asked to sign a contribution license agreement. Un comentario en la solicitud de incorporación de cambios le indicará si debe hacerlo.A comment in the PR will let you know if you do.

Importante

Si es un empleado de Microsoft y no es miembro de la organización de Microsoft en GitHub, vincule sus cuentas de Microsoft y GitHub en la red corporativa. Para hacerlo, visite Open Source en Microsoft antes de iniciar la solicitud de incorporación de cambios.If you are a Microsoft employee and are not a member of the Microsoft organization on GitHub, please link your Microsoft and GitHub accounts on corpnet by visiting Open Source at Microsoft before you start your pull request. Antes de empezar, debe seguir algunos pasos de procesamiento.There's some process stuff you'll need to do ahead of time.

Crear una solicitud de incorporación de cambiosCreating a pull request

Cuando esté listo para enviar una solicitud de extracción, cree una solicitud de extracción destinada a la rama principal.When you are ready to submit a pull request, create a pull request targeting the main branch. Para ver las correcciones de errores durante un período de estabilización de la versión, busque la rama prerelease/* más reciente.For bug fixes during a release stabilization period, look for the latest prerelease/* branch. Las nuevas características siempre deben ir a main .New features should always go into main.

Lea las instrucciones y asegúrese de que se respetan en la solicitud de incorporación de cambios.Read the guidelines and ensure your pull request meets the guidelines.

  • Asegúrese de hacer referencia a cualquier problema, solicitud de característica o tarea que guarde relación con la solicitud de incorporación de cambios.Make sure to reference any Issue / Feature Request or Task the PR relates to.
  • Compruebe que la solicitud de incorporación de cambios solo contiene los archivos o cambios correspondientes a la solicitud en cuestión.Check the pull request contains only files / changes related to the PR.
  • Compruebe que la documentación está actualizada y se incluye.Check documentation is up to date and included. Compruebe que todos los campos públicos tienen comentarios.Check all public fields have comments.
  • Si agrega una nueva característica, compruebe que se incluyen las pruebas para validarla (consulte UnitTests).If adding a new feature, check that tests are included to validate the feature (see UnitTests).
  • Si se corrige un error, escriba una prueba para comprobar la corrección.If fixing a bug, write a test to verify the bug fix.

Los responsables del mantenimiento del proyecto revisarán los cambios.The project maintainers will review your changes. Nuestro objetivo es revisar todos los cambios en un plazo de tres días hábiles.We aim to review all changes within three business days. Aborde cualquier comentario de revisión, envíe cambios a la rama puntual y publique un comentario para indicarnos si hay algo nuevo que revisar.Please address any review comments, push to your topic branch, and post a comment letting us know that there's new stuff to review.

Nota

Todas las solicitudes de incorporación de cambios que se envíen al proyecto también se revisarán de acuerdo con la Guía de estándares de programación de MRTK, por lo que debe revisarlas antes de enviarlas para garantizar un proceso sin complicaciones.All PR's submitted to the project will also be vetted according to the MRTK coding standards guide, so please review these before submitting your PR to ensure a smooth process.

Instrucciones para las solicitudes de incorporación de cambiosPull request guidelines

Estas instrucciones se basan en las prácticas de ingeniería de Google.These guidelines are based off of the Google's engineering practices.

Las solicitudes de incorporación de cambios deben ser pequeñasKeep pull requests small

Las solicitudes de incorporación de cambios más pequeñas se revisan más rápidamente y en detalle, son menos propensas a errores y más fáciles de revertir y combinar.Smaller PRs are reviewed more quickly and thoroughly, are less likely to introduce bugs, easier to roll back, and easier to merge.

Las solicitudes de incorporación de cambios deben ser lo suficientemente pequeñas como para que un ingeniero pueda revisarlas en menos de 30 minutos.Pull requests should be small enough that an engineer could review it in under 30 minutes. Intente realizar un cambio mínimo que corrija solo una cosa.Try to make a minimal change that addresses just one thing. Si necesita crear una gran solicitud de incorporación de cambios, divídala en varias para la rama local o para una rama de características de MRTK.If you must create a large PR, split it into several PRs that go into either your local branch, or a feature branch of MRTK. Evite agregar nuevos recursos (p. ej., fbx, archivos .obj) y, en su lugar, intente volver a usar los recursos existentes.Avoid adding new assets (e.g. fbx, obj files) and instead aim to re-use existing assets.

Las pruebas deben agregarse en la misma solicitud de incorporación que su corrección/característica, excepto en casos de emergencia.Tests should be added in the same PR as your fix / feature, except for emergencies

Las pruebas son la mejor manera de asegurarse de que los cambios no retrasen el código existente, pero también es fácil olvidarse de las pruebas al enviar solicitudes de incorporación de cambios.Tests are the best way to ensure changes do not regress existing code, but it is also easy to forget about tests when submitting pull requests. Requerir que pasen por su solicitud de incorporación de cambios es una excelente manera de asegurarse de que las pruebas se escriben.Requiring that they go in with your PR are a great way to ensure that tests get written.

Todas las características y correcciones de errores deben tener pruebas asociadas.Every feature and bug fix should have tests associated with it. Si no tiene experiencia o tiempo para escribir una prueba, cree un problema para escribir las pruebas y márquelo con la etiqueta Considerar para la iteración actual.If you do not have the expertise or time to write a test, create an issue to write the tests, and mark them with label Consider for Current Iteration.

La documentación debe agregarse en la misma solicitud de incorporación de cambios que una característica o corrección.Documentation should be added in the same pull request as a fix / feature

La mayoría de los desarrolladores buscan primero en la documentación, no en el código, para comprender cómo usar una característica.Most developers look first at documentation, not code, when understanding how to use a feature. Asegurarse de que la documentación está actualizada hace que sea mucho más fácil para los usuarios consumir MRTK y confiar en este.Ensuring documentation is up to date makes it much easier for people to consume and rely MRTK. La documentación siempre debe empaquetarse con incorporación de cambios relacionadas para garantizar que los elementos están actualizados y son coherentes.Documentation should always be bundled with the related pull to ensure items remain up-to-date and consistent.

Asegúrese de que cada propiedad, método y campo públicos tienen comentarios de resumen de barra diagonal triple para que nuestro sitio de docfx pueda generar descripciones de campos o métodos.Ensure every public field, method, property has triple slash summary comments so our docfx site can generate descriptions for fields / methods. Si es necesario, actualice los archivos de Markdown en la carpeta de documentación.If needed, update markdown files in Documentation folder.

Las descripciones de solicitudes de incorporación de cambios deben describir los cambios claramente y de forma completa.Pull request descriptions should clearly and completely describe changes

Las descripciones claras y completas de las solicitudes de incorporación de cambios garantizan que los revisores entienden lo que están revisando.Clear and complete descriptions of pull requests ensure reviewers understand what they are reviewing.

Si agrega características que contienen la experiencia de usuario, agregue una imagen o GIF de la característica que está cambiando.If adding features that contain UX, add an image / gif of the feature you are changing. Este es un buen ejemplo.Here is a good example. Otra sugerencia es tener un GIF de antes y después; por ejemplo, en esta solicitud de incorporación de cambios.Another suggestion is to have a gif of Before and After, for example in this pull request. Una herramienta que se recomienda para generar archivos GIF a partir de capturas de pantalla es ScreenToGif.A tool we recommend for generating gifs from screen captures is ScreenToGif.