Mejora de las descripciones de PR mediante plantillas

Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2019

Escribir buenas descripciones de PR es una excelente manera de ayudar a los revisores a saber qué esperar al revisar el código. También son una excelente forma de ayudar a realizar un seguimiento de lo que debe realizarse para cada cambio, como las pruebas, la adición de pruebas unitarias y la actualización de la documentación. Las plantillas de PR pueden ayudar a los desarrolladores a crear excelentes descripciones de PR que cumplan los estándares de su organización.

En este artículo se muestra cómo empezar a trabajar con plantillas de PR.

Nota:

Las plantillas de PR pueden proporcionar instrucciones, pero solo son de asesoramiento. Use directivas de rama para aplicar procedimientos recomendados, como requerir PR para ramas clave como principal, requerir una compilación correcta y aplicar revisores necesarios. Para obtener más información, consulte las directivas de rama.

¿Qué es una plantilla de PR?

Una plantilla de PR es un archivo que contiene texto Markdown que se agrega a la descripción de la PR cuando esta se crea.

Thank you for your contribution to the Fabrikam Fiber repo. 
Before submitting this PR, please make sure:

- [ ] Your code builds clean without any errors or warnings
- [ ] You are using approved terminology
- [ ] You have added unit tests

Azure Repos permite crear este tipo de plantillas de PR:

• Una plantilla de PR predeterminada que se aplica automáticamente a todas las PR nuevas en el repositorio, a menos que se invalide mediante una plantilla de PR específica de la rama
• Plantillas de PR específicas de rama que se aplican automáticamente a las PR destinadas a una rama específica
• Plantillas de PR adicionales que el creador de PR puede agregar opcionalmente

El tipo de plantilla de PR viene determinado por su nombre de archivo y ubicación de carpeta, como se describe en las secciones siguientes. Los nombres de archivo y las ubicaciones de carpetas no distinguen mayúsculas de minúsculas, pero deben estar en la rama predeterminada del repositorio.

Nota:

Todos los archivos de plantilla de PR deben encontrarse en la rama predeterminada (normalmente principal) del repositorio. Solo se usan archivos de plantilla de PR de la rama predeterminada.

Plantillas de PR predeterminadas

Las plantillas de PR predeterminadas se aplican automáticamente al campo de descripción cuando se crea una PR nueva. Para configurar el repositorio con una plantilla de PR predeterminada, cree un archivo denominado pull_request_template.md o pull_request_template.txt y guárdelo en la rama predeterminada del repositorio en una de estas carpetas.

• Una carpeta denominada .azuredevops que se encuentra en la carpeta raíz del repositorio
• Una carpeta denominada .vsts que se encuentra en la carpeta raíz del repositorio
• Una carpeta denominada docs que se encuentra en la carpeta raíz del repositorio
• La carpeta raíz del repositorio

Se proporcionan varias ubicaciones para ofrecer flexibilidad en la ubicación en la que se almacenan las plantillas de PR. Cuando se crea una PR, Azure Repos busca en las carpetas designadas en el orden especificado y usa la primera plantilla de PR predeterminada que encuentra.

Cuando se crea una PR nueva en el repositorio, a menos que se aplique una plantilla de PR específica de rama, el contenido de la plantilla de PR predeterminada se usa para rellenar previamente el campo de descripción en la PR.

Puede editar o agregar a esta descripción y anexar plantillas de PR adicionales si lo quiere seleccionándolas en la lista desplegable Agregar una plantilla.

Nota:

Cuando se aplica automáticamente una plantilla de PR predeterminada o específica de rama, reemplaza los mensajes de confirmación estándar que normalmente se usan para la descripción predeterminada. Puede volver a agregarlos seleccionando Agregar mensajes de confirmación.

Plantillas de PR específicas de rama

Las plantillas de PR específicas de rama se pueden configurar para las PR que tienen como destino una rama específica. Para configurar el repositorio con una plantilla de PR específica de la rama, cree un archivo .txt o .md cuyo nombre esté relacionado con la rama. El nombre debe coincidir con el primer nivel del nombre de la rama, como main, dev, release o feature. Cada plantilla de PR específica de rama se aplica cada vez que una PR tiene como destino esa rama o cualquier rama contenida en ella. Por ejemplo, la plantilla de PR denominada feature.md se aplicaría si una PR tiene como destino la rama feature o cualquier rama feature/*.

Las plantillas de PR específicas de rama deben guardarse en la rama predeterminada del repositorio mediante esta jerarquía de carpetas: pull_request_template/branches/. Estas carpetas deben basarse en una de estas carpetas del repositorio.

• Una carpeta denominada .azuredevops que se encuentra en la carpeta raíz del repositorio
• Una carpeta denominada .vsts que se encuentra en la carpeta raíz del repositorio
• Una carpeta denominada docs que se encuentra en la carpeta raíz del repositorio
• La carpeta raíz del repositorio

Por ejemplo, una plantilla de PR específica de rama que se debe aplicar a todas las PR en la rama dev se denominaría dev.md o dev.txt y se ubicaría en una de estas ubicaciones.

• <repository root>/.azuredevops/pull_request_template/branches/
• <repository root>/.vsts/pull_request_template/branches/
• <repository root>/docs/pull_request_template/branches/
• <repository root>/pull_request_template/branches/

Al igual que las plantillas de PR predeterminadas, se proporcionan varias ubicaciones para proporcionarle flexibilidad en la ubicación en la que se almacenan las plantillas de PR específicas de la rama. Cuando se crea una PR, Azure Repos busca en las carpetas designadas en el orden especificado para una plantilla de PR específica de una rama y usa la primera que encuentra que coincide con el nombre de la rama. Si no se encuentra ninguna plantilla de PR específica de rama, Azure Repos busca una plantilla de PR predeterminada como se describe en la sección anterior Plantillas de PR predeterminadas.

Plantillas de PR adicionales

Además de las plantillas de PR específicas de rama y predeterminadas, puede configurar plantillas de PR adicionales. Pueden ser archivos .md o .txt, ubicados en una de estas carpetas de la rama predeterminada.

• <repository root>/.azuredevops/pull_request_template/
• <repository root>/.vsts/pull_request_template/
• <repository root>/docs/pull_request_template/
• <repository root>/pull_request_template/

Cuando se crea una PR, puede anexar cualquiera de las plantillas de PR disponibles eligiéndolas de la lista desplegable Agregar una plantilla. Los nombres en la lista desplegable se basan en los nombres de archivo de las plantillas.

En el ejemplo siguiente se muestran tres plantillas.

• dev.md: esta es la plantilla específica de la rama que se aplicó de forma predeterminada a esta PR en la rama de desarrollo, como se indica en el mensaje predeterminado enumerado después del nombre de archivo.
• additional.md: es una plantilla adicional.
• pull_request_template.md: normalmente es la plantilla predeterminada, pero la plantilla dev.md específica de la rama la invalida en esta PR. Aunque no se agregó de forma predeterminada, todavía se puede aplicar seleccionándola en la lista.

Seleccione el nombre de la plantilla adicional deseada para anexar su contenido a la descripción de la PR actual.

Nota:

Puede especificar una plantilla de PR para invalidar cualquier PR predeterminada o específica de rama coincidente anexando ?template=name.md a la cadena de consulta.

Vea también

• Creación de una solicitud de incorporación de cambios para revisar y combinar código
• Acerca de las ramas y las directivas de rama