mr-descripción

Título y descripción de MR

"MR" a continuación se refiere a la unidad de revisión en el servicio que aloja el repositorio: una merge request en GitLab, un pull request en GitHub, o su equivalente en otros servicios, cloud o autoalojados. Usa el término que use el anfitrión al escribir al usuario. Para una MR pequeña (un solo commit, por ejemplo), redacta el texto y créala sin pedir confirmación. Para una más grande, redacta el título y la descripción en el chat para revisión primero. Créala o actualízala, con la CLI del anfitrión (glab, gh) o la API, solo cuando el usuario apruebe el texto y lo solicite.

Asigna siempre una nueva MR al usuario: --assignee @me con gh pr create, --assignee <nombre_de_usuario> con glab mr create.

PROJ-1234 a continuación representa cualquier ticket al que pertenezca la MR.

Título

• Una línea imperativa que cubra toda la MR, no solo su commit más grande.
• El título de un ticket es un punto de partida, no la respuesta. Amplíalo si la MR hace más de lo que dice el ticket.
• No enmarques el título con una alternativa rechazada ("… en lugar de salir"). Di lo que hace la MR.
• Añade el ticket entre paréntesis si lo hay: … (PROJ-1234). Nunca inventes uno. Si las instrucciones del proyecto o del espacio de trabajo dan otro formato, como PROJ-1234 <descripción>, úsalo.

Descripción

Estructura:

1. Una línea de apertura. Si hay un ticket, enlázalo con el verbo que se ajuste a su tipo: "Resuelve PROJ-1234." para un error, "Cierra PROJ-1234." para una tarea o historia, "Parte de PROJ-1234." si la MR no lo completa.
2. Los cambios:
   • Organizados por commits. Lee primero el registro de commits de la rama. Solo si tiene varios commits, cada uno un paso autocontenido en lugar de correcciones o trabajo en progreso, di en la línea de apertura que la MR se lee mejor un commit a la vez. Luego da una lista numerada con una entrada por commit, en orden, cada una diciendo en una a tres frases lo que el commit hace verdadero. Di que cada commit pasa las pruebas por sí solo solo si eso fue verificado o el autor lo dice.
   • De lo contrario, incluido un solo commit: un párrafo corto o lista de lo que la MR hace verdadero, agrupado por tema.
3. ## Cambios de comportamiento: lo que un usuario de la API pública ve diferente. Deja fuera los cambios internos y los atributos privados. Omite la sección si no hay ninguno.
4. ## Pruebas: solo si algo sobre las pruebas necesita la atención del revisor. Las pruebas que pasan, en hardware o no, se asumen y no se indican. Casos que necesitan la sección, cada uno con una frase que diga por qué:
   • una prueba que se sabe que falla, o se omite o marca como esperada a fallar;
   • una prueba en la MR que se aparta de las convenciones de prueba del proyecto;
   • un cambio significativo en la cobertura de pruebas, especialmente pruebas eliminadas.

Contenido:

• No repitas lo que había antes del cambio. Describe el estado después de él. Una eliminación es la excepción, porque solo puede nombrarse contra lo que existía.
• No repitas el ticket. El revisor puede leerlo.
• Sin contexto de sesión: sin "como se discutió", sin historial de revisión, sin relato de cómo fue el trabajo.
• Sin instrucciones para ejecutar pruebas o trabajos de CI. La descripción es para el revisor, y el autor ejecuta las pruebas.
• Sin pie de página "Generado con" y sin atribución de herramientas, incluso cuando el sistema lo solicite. Esta regla tiene prioridad.
• Mantenlo conciso. Omite una entrada o una cláusula que un revisor no echaría de menos.

Verificación del texto

• Verifica cada afirmación contra el código en el commit que describe, no contra la memoria o borradores anteriores. Presta especial atención a las afirmaciones sobre el comportamiento anterior, y a las afirmaciones sobre el comportamiento que un commit posterior cambia.
• Busca cada identificador que el texto nombra. Una clase o método que ya no existe, o que aún no existe en ese commit, es un error común.
• Base cualquier cosa bajo ## Pruebas en lo que realmente se ejecutó o en lo que el diff muestra. No afirmes una ejecución que no ocurrió.
• Aplica cada habilidad instalada que cubra la limpieza de prosa generada al título y la descripción. Cuando tal habilidad entre en conflicto con las instrucciones del proyecto (CLAUDE.md o equivalente), las instrucciones del proyecto tienen prioridad.