Respuesta rápida: las tres preguntas
Si usas los issues de GitHub para dar seguimiento al trabajo, seguramente has notado el botón de “Crear una rama” en la barra lateral de un issue.
Es tentador hacer clic en él para cada issue, pero vincular una rama a un issue es un compromiso pequeño con efectos reales en cómo se muestra tu trabajo a tus colaboradores.
Esta guía explica qué sucede realmente cuando creas una rama para un issue, cuándo la conexión ayuda y cuándo es mejor esperar.
Toda la decisión se reduce a tres preguntas, hechas en orden:
- ¿Estoy empezando a trabajar en este issue ahora mismo?
- ¿Alguien más está empezando a trabajar y puedo vincular su rama manualmente?
- ¿Este issue sigue siendo una discusión sin decidir?
Si respondiste sí a la primera, crea la rama desde la página del issue.
Si fue la segunda, vincula la rama existente desde la barra lateral del issue.
Si fue la tercera, espera hasta que alguien se comprometa con una solución.
El resto de esta guía explica por qué.
Qué hace realmente crear una rama para un issue
GitHub permite que cualquier persona con permiso de escritura en un repositorio cree una rama directamente desde la página de un issue.
Abres el issue, buscas la sección “Development” en la barra lateral derecha y eliges “Create a branch”.
Opcionalmente puedes nombrar la rama, elegir un repositorio de destino y decidir si trabajas localmente o abres la rama en GitHub Desktop.
Por defecto, la nueva rama se crea en el repositorio actual y a partir de la rama predeterminada.
Lo importante es la conexión, no la rama en sí.
Las ramas conectadas a un issue aparecen en la sección “Development” de la barra lateral del issue.
Esa sección es una señal visible para cualquiera que lea el issue: alguien ya empezó a trabajar en esto.
También puedes vincular varias ramas a un mismo issue, algo útil cuando varias personas abordan el mismo problema desde ángulos distintos.
Nota: crear una rama para un issue está en vista previa pública en GitHub y puede cambiar.
Si tu equipo construye un flujo de trabajo alrededor de ella, espera que la interfaz o el comportamiento evolucionen.
Cómo cambia la conexión al abrir un pull request
Aquí está el comportamiento que sorprende a la gente.
Cuando creas un pull request para una rama conectada a un issue, el pull request se vincula automáticamente al issue.
En ese momento, la conexión con la rama se elimina y solo el pull request se muestra en la sección “Development”.
El issue no termina listando tanto la rama como el pull request; el pull request toma el relevo como marcador visible del trabajo en curso.
Esto importa para la planificación.
Si esperas que el issue muestre un rastro de todas las ramas creadas para él, no lo hará.
La barra lateral refleja el estado actual: o una rama en progreso o un pull request, no un historial de ambos.
Cuándo crear una rama para un issue ayuda
La conexión gana su lugar en tres situaciones comunes.
- Estás empezando a trabajar de inmediato. La función existe para que puedas comenzar al instante desde la página del issue. Si acabas de triar un issue y estás por escribir código, crear la rama desde el issue es la forma más rápida de empezar y de señalar que el trabajo comenzó.
- Los colaboradores necesitan ver el estado de un vistazo. Una rama vinculada le dice a cualquiera que abra el issue que hay una solución en progreso, sin necesidad de un comentario que lo diga. En repositorios compartidos, esa visibilidad reduce el esfuerzo duplicado y las preguntas de “¿alguien está en esto?”.
- Quieres un vínculo automático más adelante. Como un pull request de una rama conectada se vincula automáticamente al issue, te ahorras un paso manual después. Ese vínculo automático también habilita el cierre automático, descrito abajo.
Una ilustración práctica: un equipo pequeño tria los issues el lunes.
Para cada issue que alguien toma ese día, crea una rama desde la página del issue.
Para el martes, cada issue en progreso muestra una rama en “Development”, y cada issue sin tocar no muestra nada.
La barra lateral se convierte en el tablero de estado honesto del equipo, sin ceremonia extra.
Cuándo es mejor esperar
Crear una rama es barato, pero una rama vinculada es una afirmación pública de que hay trabajo en marcha.
Espera cuando esa afirmación aún no sea cierta.
- El issue sigue siendo una discusión. Muchos issues empiezan como preguntas o reportes de problemas. Si nadie se ha comprometido con una solución, una rama vinculada induce a error al hacer creer que alguien está programando. Deja el issue sin vincular hasta que se elija una dirección.
- Estás explorando varios enfoques. Si quieres prototipar en privado antes de comprometerte con una solución, una rama local sin vincular mantiene el issue limpio. Siempre puedes crear la rama conectada después, cuando un enfoque se asiente.
- La solución aún no tiene alcance definido. Si la solución podría abarcar varios issues o una refactorización, puede ser más claro crear la rama cuando el alcance sea conocido, para que la conexión apunte a un trabajo que realmente aborda el issue.
También hay una consideración de mantenimiento.
Cada rama conectada es una rama en tu repositorio.
Si creas ramas especulativas para issues que nunca avanzan, acumulas ramas obsoletas que alguien eventualmente tendrá que limpiar.
Crear la rama cuando empieza el trabajo, no cuando se abre el issue, mantiene esa deuda baja.
Cómo los pull requests cierran issues vinculados automáticamente
La principal recompensa de vincular es el cierre automático.
Cuando fusionas un pull request vinculado en la rama predeterminada, su issue vinculado se cierra automáticamente.
No necesitas recordar cerrar el issue a mano.
Puedes lograr el mismo efecto sin crear una rama desde el issue, usando una palabra clave de cierre en la descripción del pull request o en un mensaje de commit.
Las palabras clave admitidas incluyen close, closes, closed, fix, fixes, fixed, resolve, resolves y resolved, seguidas de la referencia al issue.
Para un issue en el mismo repositorio, la sintaxis es la palabra clave más el número del issue, como “Closes #10”.
Para un issue en otro repositorio, usa el propietario y el nombre del repositorio en la referencia.
Las palabras clave pueden escribirse con dos puntos o en mayúsculas, así que “Closes: #10” y “CLOSES #10” funcionan igual.
Puedes referenciar varios issues dando la sintaxis completa para cada uno.
Dos limitaciones importan.
Primera: las palabras clave de cierre solo se interpretan cuando el pull request apunta a la rama predeterminada del repositorio.
Si el pull request apunta a cualquier otra rama, las palabras clave se ignoran, no se crean vínculos y la fusión no tiene efecto sobre los issues.
Segunda: si usas una palabra clave de cierre en un mensaje de commit, el issue se cierra cuando el commit se fusiona en la rama predeterminada.
Sin embargo, el pull request que contiene ese commit no aparecerá listado como pull request vinculado.
Si quieres el vínculo visible, pon la palabra clave en la descripción del pull request o vincula manualmente.
Vinculación y desvinculación manuales
No estás limitado al flujo de “Crear una rama”.
Quien tenga permiso de escritura puede vincular manualmente un pull request a un issue o una rama desde la barra lateral correspondiente.
Puedes vincular manualmente hasta diez issues a cada pull request.
Al vincular desde la barra lateral del issue, el issue puede estar en un repositorio distinto al del pull request o la rama.
Al vincular desde la barra lateral del pull request, el issue y el pull request deben estar en el mismo repositorio.
La desvinculación tiene una asimetría que recordar.
Solo los pull requests vinculados manualmente pueden desvincularse manualmente.
Si vinculaste un issue usando una palabra clave, eliminas el vínculo editando la descripción del pull request para borrar la palabra clave.
Planifica con eso en mente si podrías cambiar a qué issue responde un pull request.
Un camino de decisión simple Únelo todo en tres preguntas, hechas en orden. ¿Estoy empezando a trabajar en este issue ahora? Si sí, crea la rama desde la página del issue. Obtienes la señal visible y el vínculo automático del pull request después. ¿Alguien más está empezando a trabajar y tengo los datos de la rama? Si el trabajo está ocurriendo pero la rama se creó fuera de GitHub, vincúlala manualmente desde la barra lateral del issue para que el estado siga visible. ¿Este issue sigue sin decidirse? Entonces espera. Mantén el issue como discusión y crea o vincula una rama solo cuando alguien se comprometa con una solución. El principio de fondo es la honestidad de la señal. La sección “Development” solo es útil si significa “hay trabajo en progreso en este issue ahora mismo”. Cada rama especulativa que agregas diluye ese significado para todos los que leen el repositorio. Qué significa esto para equipos pequeños y fundadores en solitario
Si eres fundador u operador temprano que usa GitHub para un proyecto paralelo, quizá te preguntes si esto importa cuando eres el único contribuidor.
Aún importa, por dos razones.
Primera: el cierre automático al fusionar te salva de una lista de issues obsoletos, uno de los artefactos más desmoralizantes de un proyecto descuidado.
¿Crear una rama para un issue vincula el pull request automáticamente?
Sí, de forma indirecta.
La rama misma queda vinculada al issue, y al abrir un pull request para esa rama, el pull request se vincula automáticamente al issue.
Entonces la conexión con la rama se elimina y solo el pull request aparece en la sección “Development”.
¿Puedo vincular más de una rama a un issue?
Sí.
GitHub documenta que puedes vincular varias ramas a un issue, lo cual encaja con situaciones donde varias personas trabajan el mismo problema en paralelo.
¿Las palabras clave de cierre funcionan en cualquier pull request?
No.
Las palabras clave solo se interpretan cuando el pull request apunta a la rama predeterminada del repositorio.
Los pull requests dirigidos a otras ramas las ignoran por completo.
¿Qué pasa si vinculé el issue equivocado?
Si el vínculo fue manual, puedes desvincularlo.
Si vino de una palabra clave, edita la descripción del pull request para quitar la palabra clave, porque los vínculos basados en palabras clave no pueden desvincularse manualmente.
La conclusión
Crea una rama para un issue cuando el trabajo realmente está empezando y quieres que el issue lo muestre, y espera cuando el issue sigue siendo una conversación.
Incluye una palabra clave de cierre en la descripción del pull request para cerrar el issue al fusionar; funciona solo con la rama predeterminada.
La función está en vista previa pública; la interfaz puede cambiar, pero conectar el trabajo al issue sigue siendo valioso.
Para los pasos oficiales y el comportamiento actual, consulta la documentación de GitHub sobre crear una rama para un issue y sobre vincular un pull request a un issue.
Si estás decidiendo cómo estructurar el trabajo antes de crear ramas, un issue demasiado extenso suele conviene dividirlo primero.
Acordar las normas del equipo desde el inicio puede evitar debates sobre hábitos de ramificación más adelante.
Da el siguiente paso con Ideoreto.
Usa las ideas de esta guía como punto de partida para tu próximo proyecto.
Regístrate en Ideoreto para comenzar.