Los issues de GitHub son una de las funcionalidades más poderosas para gestionar mejoras, reportar errores y facilitar la colaboración en cualquier repositorio. Saber cómo usarlos correctamente y cómo crear plantillas personalizadas marca la diferencia entre un proyecto desorganizado y uno que invita a contribuir de forma clara y eficiente.
¿Qué son los issues en GitHub y para qué sirven?
Un issue permite señalar un defecto o área de mejora dentro de un repositorio [0:03]. Estos defectos pueden ir desde algo tan simple como un error tipográfico en la documentación, como un acento o signo de puntuación faltante, hasta problemas complejos donde la solución no funciona de la manera esperada.
Gracias a los issues, cualquier persona puede hacerle saber al autor del repositorio que existe un problema que puede ser solucionado. Quien reporta puede decidir si desea contribuir activamente a la solución o simplemente señalar que algo no está funcionando como debería [0:28].
¿Cómo se crea un issue en un repositorio?
Dentro de tu repositorio en GitHub, selecciona la pestaña de Issues y haz clic en el botón de nuevo issue [0:44]. El formulario solicita dos campos fundamentales:
- Título: una descripción breve del problema.
- Descripción: los detalles de lo que está sucediendo.
Además de estos campos, existe un panel lateral donde puedes asignar la tarea a alguien, agregar etiquetas y otros elementos adicionales [1:06]. Una vez enviado, el issue aparece con un número identificador y se convierte en un espacio de conversación donde se puede discutir el problema reportado [1:22].
¿Por qué es importante que otros levanten issues en tu repositorio?
Lo ideal no es que tú mismo reportes problemas, sino que otras personas identifiquen qué puedes mejorar [1:32]. Para facilitarles ese proceso, puedes crear plantillas de issues que funcionen como formularios estructurados, guiando a los usuarios para que expliquen con claridad qué fue lo que encontraron.
¿Cómo crear una plantilla de issue en GitHub?
El proceso requiere trabajar directamente con la estructura de archivos del repositorio. Desde tu terminal, abre el repositorio con Visual Studio Code usando el comando code . [1:52].
Los pasos son los siguientes:
- Crea una carpeta llamada
.github en la raíz del proyecto. El punto al inicio es obligatorio para que GitHub la reconozca [2:03].
- Dentro de
.github, crea otra carpeta llamada ISSUE_TEMPLATE en mayúsculas [2:13].
- En esa segunda carpeta, crea un archivo llamado
bug_report.md. La extensión .md indica que es un archivo Markdown, el mismo formato del README [2:22].
Dentro de este archivo se coloca el contenido de la plantilla, que incluye secciones para describir el problema, los pasos para reproducirlo y cualquier información relevante que necesites para entender el error [2:38]. Estas secciones le dan al usuario una guía clara de qué información aportar al momento de levantar un issue.
¿Cómo subir la plantilla a GitHub desde Visual Studio Code?
Una vez guardados los cambios, Visual Studio Code muestra los archivos nuevos en color verde, indicando que hay cambios pendientes en el control de versiones [2:57]. En la sección de source control:
- Escribe un mensaje de commit como "Bug Report agregado" [3:10].
- Haz clic en commit.
- Selecciona el botón de sincronizar cambios con la flecha hacia arriba, que indica que los cambios se subirán a la nube de GitHub [3:17].
- La primera vez aparecerá una ventana configurando los comandos de pull y push. Selecciona OK y espera la sincronización [3:26].
Al regresar a GitHub y visitar la sección de code, verás la carpeta .github con el issue template ya disponible [3:40].
¿Qué cambia en la experiencia del usuario al usar plantillas?
Cuando alguien quiera levantar un nuevo issue, ahora verá la opción de Bug Report como tipo de reporte disponible [3:52]. Al seleccionarla, la plantilla aparece prellenada con las secciones que definiste, solicitando un título, una descripción breve y toda la información necesaria para reproducir el error con claridad [4:00].
Esto transforma la experiencia de contribución: en lugar de recibir reportes vagos, obtienes información estructurada que te permite actuar con rapidez. Puedes crear múltiples plantillas para distintos escenarios, como reportes de documentación o mejores prácticas [4:22].
¿Ya tienes ideas para las plantillas que podrías agregar a tus repositorios? Comparte en los comentarios qué tipos de issues te resultan más útiles.
