Blog

Cómo vincular ramas, commits y pull requests a las incidencias

Pregunta a un equipo a qué incidencia pertenece un pull request y la respuesta suele ser una pausa seguida de una búsqueda. Pregunta qué código se entregó para una incidencia concreta y la respuesta es revisar el historial de commits. Ambas preguntas se responden en segundos cuando existe un solo hábito: la clave de la incidencia viaja con el trabajo, desde el nombre de la rama hasta el mensaje del commit y el pull request.

Ese hábito no necesita un proceso nuevo ni una herramienta nueva. Necesita unas pocas convenciones sencillas, aplicadas siempre de la misma manera. Esta guía explica esas convenciones, los errores que las rompen sin hacer ruido y cómo ISO Mate las aprovecha para mostrar el código de cada incidencia sin que nadie rellene un formulario.

Por qué la clave de la incidencia es el vínculo

Git no sabe nada de tu gestor de incidencias. Una rama, un commit y un pull request son solo nombres y texto. La única forma de conectarlos con un trabajo planificado es escribir en ese texto algo que una persona o una herramienta pueda reconocer más tarde. La clave de la incidencia (por ejemplo PROJ-42) es ideal porque es corta, única y ya es la forma en que el equipo se refiere al trabajo.

Cuando la clave está en el texto que Git conserva, muchas preguntas tediosas se vuelven fáciles. Quien revisa ve por qué existe un cambio. Quien redacta el resumen de la versión ve qué cambios pertenecen a qué incidencias. Quien depura una regresión meses después puede ir de una línea de código al commit y a la razón por la que se escribió. Y cuando un auditor o un cliente pregunta qué cambio cubrió un requisito concreto, puedes responder con el registro en lugar de la memoria.

Los cinco hábitos

  1. Usa claves que nunca cambien.
  2. Nombra la rama con la clave.
  3. Empieza los mensajes de commit con la clave.
  4. Pon la clave en el título del pull request.
  5. Decide qué significa una fusión para la incidencia.

1. Usa claves que nunca cambien

Una clave solo funciona como vínculo si identifica un único elemento durante todo el tiempo que exista el código. Si las claves se pueden renumerar, reutilizar o reescribir cuando un elemento cambia de tipo, cada nombre de rama y mensaje de commit antiguo se convierte en una referencia muerta. Elige un prefijo corto y reconocible para cada proyecto, como API o WEB, y trata el número como permanente.

La solución: elige un gestor que nunca reescriba las claves y acuerda un prefijo por proyecto antes de crear la primera rama. En ISO Mate la clave del proyecto tiene de 2 a 10 letras mayúsculas o números y queda fija al crear el proyecto. Además, una incidencia conserva su clave aunque más tarde cambies su tipo de Task a Bug, así que las referencias en los mensajes de commit siguen siendo válidas.

2. Nombra la rama con la clave

La rama es lo primero que se crea al empezar a trabajar, así que es el primer punto en el que se puede establecer el vínculo. Un patrón coherente también hace que las ramas se puedan ordenar y leer en cualquier herramienta de Git.

La solución: acuerda un patrón y úsalo en todas partes. Una opción habitual es feature/PROJ-42-add-invoice-export: un tipo, la clave y un identificador corto del resumen. Mantén la clave al principio, el identificador breve y procura tener una rama por incidencia. Si una rama lleva tres incidencias sin avisar, el vínculo es cierto para las tres y útil para ninguna.

3. Empieza los mensajes de commit con la clave

Los commits son donde el vínculo dura más, porque el historial de commits es permanente incluso después de borrar las ramas. Un mensaje como PROJ-42 Add CSV export for invoices se puede buscar por clave y se lee de un vistazo.

La solución: empieza con la clave y sigue con una descripción clara del cambio. Procura una incidencia por commit. Una advertencia: si tu equipo fusiona con squash, los commits individuales se convierten en uno y el mensaje de ese commit suele proceder del pull request. Eso hace que el siguiente hábito sea el más importante de los dos.

4. Pon la clave en el título del pull request

El pull request es lo que realmente miran quienes revisan, gestionan y publican versiones. Un título como PROJ-42 Add CSV export for invoices les dice para qué sirve el cambio antes de abrirlo. La descripción es el lugar para las claves relacionadas, el contexto y todo lo que quien revisa deba comprobar.

La solución: abre el pull request como borrador en cuanto haya algo que mostrar. Así el vínculo existe mientras el trabajo está en curso y quien gestiona el proyecto puede ver que la incidencia tiene código detrás sin preguntar. Si un mismo pull request cubre de verdad más de una incidencia, nombra cada clave. También es una señal para preguntarse si el cambio debería haberse dividido.

5. Decide qué significa una fusión para la incidencia

Vincular código a una incidencia y terminar una incidencia son cosas distintas. Un pull request fusionado no significa necesariamente que el trabajo esté hecho. Puede faltar un despliegue, una ronda de pruebas o una comprobación frente a los criterios de aceptación. Los equipos que omiten esta decisión acaban con incidencias marcadas como Done que nadie ha verificado, o con incidencias en In Progress mucho después de que su código se entregara.

La solución: deja por escrito quién mueve la incidencia y en qué momento: al fusionar, al desplegar o tras la verificación. Luego inclúyelo en tu definición de terminado en lugar de dejarlo a la memoria.

Cuatro formas en que el vínculo se rompe sin hacer ruido

  • Una errata en la clave. Escribir PROJ-24 en lugar de PROJ-42 vincula el trabajo a otra incidencia real. No salta ningún error, así que la incidencia equivocada muestra una actividad que no le corresponde. Copia la clave desde la incidencia en lugar de teclearla.
  • Empezar antes de que exista la incidencia. El trabajo que empieza en una rama sin nombre recibe su clave más tarde, si es que la recibe. Crear la incidencia lleva un minuto y ahorra la limpieza.
  • Ramas de larga duración. Una rama que permanece abierta durante semanas y acumula varias incidencias resta valor a cada vínculo. Las ramas más pequeñas también significan revisiones más pequeñas y sencillas.
  • La clave solo en la descripción. Algunas herramientas leen únicamente el título. Pon la clave principal en el título y usa la descripción para lo demás.

Cómo ISO Mate hace el vínculo por ti

Estos hábitos no dependen de ninguna herramienta, pero rinden más cuando algo lee las claves por ti. Eso es lo que hacen las Integraciones Git de Proyectos de ISO Mate. Así se corresponde cada hábito con lo que hace la plataforma.

  • Claves: las incidencias de un proyecto toman la clave del proyecto como prefijo, de modo que un proyecto con la clave PROJ produce PROJ-1, PROJ-2 y así sucesivamente. Las incidencias sin proyecto usan un prefijo por tipo (EPC, USR, TSK, BUG o SUB). La guía de claves de incidencia explica la numeración.
  • Conectar un repositorio: en la configuración de un proyecto, agrega una conexión a GitHub, GitLab o Bitbucket con un token de acceso. ISO Mate valida el token y detecta si tiene acceso de solo lectura o de lectura y escritura.
  • Coincidencia: cada 15 minutos, ISO Mate sincroniza las ramas, los commits y los pull requests de cada repositorio conectado. Busca claves de incidencia en los nombres de rama, los mensajes de commit y los títulos y descripciones de los pull requests, y vincula lo que encuentra con la incidencia correspondiente. La coincidencia no distingue mayúsculas de minúsculas, y un pull request que nombra dos claves se vincula a ambas. Una clave solo se vincula si existe una incidencia con esa clave.
  • Actividad Git en la incidencia: abre una incidencia y su sección Actividad Git muestra las ramas, los commits y los pull requests vinculados, agrupados por repositorio, con un enlace al proveedor. Los pull requests muestran su estado, y una acción de actualización sincroniza la incidencia al momento en lugar de esperar al siguiente ciclo.
  • Empezar a trabajar desde la incidencia: Crear Rama genera un nombre a partir de la clave y el resumen de la incidencia. El patrón predeterminado es feature/{KEY}-{summary}, y cada proyecto puede definir su propio Patrón de Rama Predeterminado. Puedes copiar el nombre de la rama o un comando de checkout ya preparado. Crear MR/PR abre un pull request que lleva la clave de la incidencia en el título y lo inicia como borrador. Ambas acciones requieren una conexión con acceso de escritura.
  • Poner orden: cada rama y cada pull request tiene un menú de acciones para desvincularlo de la incidencia y, con acceso de escritura, para eliminar la rama o cerrar un pull request abierto en el proveedor tras una confirmación.

Hay límites que conviene conocer antes de confiar en ello. La sincronización funciona en ciclos de 15 minutos, así que una rama recién creada puede tardar ese tiempo en aparecer si no actualizas. ISO Mate no cambia el estado de una incidencia cuando se fusiona un pull request, por lo que el quinto hábito sigue siendo una decisión del equipo. Y una vez creado un vínculo, no se elimina automáticamente si editas un título, así que si una errata vinculó la incidencia equivocada, desvincúlala desde la sección Actividad Git.

Un punto de seguridad: usa el menor acceso que necesites. Si tu equipo de desarrollo crea ramas y pull requests con sus propias herramientas, un token de solo lectura basta para que ISO Mate sincronice y vincule. Concede acceso de escritura solo si quieres crear ramas y pull requests desde la incidencia. La guía de configuración enumera los permisos del token para cada proveedor.

Cinco preguntas para revisar con tu equipo

  1. ¿Tiene cada incidencia una clave que nunca se renumerará ni se reutilizará?
  2. ¿Todos nombran las ramas con el mismo patrón, con la clave primero?
  3. ¿Los mensajes de commit y los títulos de los pull requests empiezan con la clave?
  4. ¿Puedes abrir cualquier incidencia y ver el código que hay detrás, y abrir cualquier pull request y nombrar su incidencia?
  5. ¿Sabe el equipo quién mueve una incidencia a Done y cuándo?

Si la respuesta a alguna es no, empieza por el hábito más cercano al principio de la lista, porque cada uno hace más valioso al siguiente. Para ver los vínculos en tus propias incidencias, conecta un repositorio a un proyecto en Gestión DevOps. Todas las cuentas de ISO Mate empiezan con una prueba gratuita de 14 días.

Leave a Reply