Un buen issue en GitHub le da al mantenedor todo lo que necesita para reproducir tu problema y nada que no necesite. Antes de abrir uno, busca entre los issues existentes; luego usa la plantilla de issues del repositorio, escribe un titulo especifico e incluye un ejemplo minimo reproducible, tus versiones exactas y lo que esperabas frente a lo que realmente paso. Mantenlo en un problema por issue, formatealo con bloques de codigo de markdown y ten paciencia – la mayoria de los mantenedores son voluntarios. Un issue que alguien puede reproducir en dos minutos es un issue que se arregla.
Como Escribir un Buen Issue en GitHub: Paso a Paso
- Busca primero entre los issues abiertos y cerrados. Tu bug puede que ya este reportado, arreglado o explicado – comenta ahi en vez de abrir un duplicado.
- Revisa CONTRIBUTING.md y las plantillas de issues. Muchos proyectos dirigen las preguntas a Discussions y reservan los issues para bugs y funcionalidades.
- Elige la plantilla correcta y un solo problema. Elige “bug report” o “feature request”, y abre un issue separado para cada problema distinto.
- Escribe un titulo especifico. Resume el sintoma real, como un buen mensaje de commit – no “No funciona.”
- Agrega un ejemplo minimo reproducible. Proporciona el fragmento ejecutable mas pequeno, un repositorio de ejemplo o los pasos exactos que disparan el bug.
- Plantea el comportamiento esperado vs. el real y tu entorno. Incluye la version exacta del paquete, el sistema operativo y el runtime, mas el error completo o los logs en un bloque de codigo.
- Envialo y luego mantente atento. Responde a las preguntas de seguimiento del mantenedor para que el issue no quede estancado.
Que Hacer y Que No Hacer
Que hacer:
- Busca entre los issues abiertos y cerrados existentes antes de abrir uno.
- Sigue la plantilla de issues y la guia de contribucion del repositorio.
- Escribe un issue claro y especifico por problema.
- Incluye un ejemplo minimo reproducible y las versiones exactas.
- Usa bloques de codigo de markdown para codigo, logs y stack traces.
Que no hacer:
- Abrir un duplicado sin revisar primero.
- Abrir un issue vago de “no funciona” sin reproduccion.
- Juntar varios bugs sin relacion en un solo issue.
- Mencionar con @ o enviar mensajes directos a los mantenedores para exigir un arreglo rapido.
- Acumular comentarios de “+1” o “a mi tambien” – usa una reaccion 👍 en su lugar.
Busca Antes de Abrir un Issue
Los issues abiertos son solo la mitad del panorama – busca tambien entre los issues cerrados. Un issue cerrado muchas veces contiene el arreglo, la solucion temporal o la razon del mantenedor para “won’t fix”. Si encuentras un issue abierto que coincide, agrega ahi tus detalles de reproduccion o tu entorno en vez de abrir un duplicado; eso consolida la senal que los mantenedores usan para priorizar. Usa la busqueda de issues de GitHub con calificadores como is:issue tu texto de error para abrirte paso entre el ruido.
Usa la Plantilla de Issues (y el Canal Correcto)
La mayoria de los repositorios establecidos incluyen plantillas de issues – un formulario de reporte de bug, un formulario de solicitud de funcionalidad, a veces una opcion de issue en blanco que esta deliberadamente desactivada. Completa la plantilla por completo en vez de borrar las indicaciones; cada campo esta ahi porque los mantenedores se cansaron de pedirlo.
Antes de eso, revisa por encima CONTRIBUTING.md. Muchos proyectos envian las preguntas de uso a GitHub Discussions, a un foro comunitario o a Stack Overflow, y mantienen el rastreador de issues estrictamente para bugs y solicitudes de funcionalidad. Publicar una pregunta de como hacer algo como issue en esos repos normalmente solo hace que lo cierren con un enlace al lugar correcto.
El Corazon de un Buen Issue: Un Ejemplo Reproducible
Todo lo demas es secundario frente a esta unica pregunta: puede el mantenedor reproducir tu problema? Dale un ejemplo minimo reproducible – el fragmento ejecutable mas pequeno, un repositorio de ejemplo o la secuencia exacta de pasos que dispara el bug en una configuracion limpia. “A veces falla” no es accionable; “ejecutar npm test en un clon fresco de este repro de 15 lineas lanza el stack trace de abajo” si lo es.
Si estas reportando un bug en vez de solicitar una funcionalidad, vuelca tu ejemplo directamente en nuestra plantilla de reporte de bug – sus campos de “Pasos para reproducir” y “Entorno” estan hechos exactamente para esto.
Incluye Versiones y Entorno
“Latest” no es una version. Da la version exacta del paquete (o el SHA del commit), el sistema operativo y la version del lenguaje o el runtime – v2.4.1, macOS 14.5, Node 20.11. Los bugs frecuentemente son especificos de una version, y un mantenedor que no puede saber en que release estas perdera una ida y vuelta solo en preguntarlo. Pega el mensaje de error completo y cualquier log relevante; un error truncado normalmente oculta la linea que realmente importa.
Formatealo Como Si Te Importara
Los issues de GitHub son markdown, asi que usalo. Envuelve el codigo, los comandos y los stack traces en bloques de tres comillas invertidas con una pista de lenguaje para el resaltado de sintaxis. Colapsa los logs muy largos dentro de un bloque <details> para que el issue siga siendo legible. Etiqueta las partes clave – Esperado, Real, Pasos para reproducir – y enlaza a lineas especificas de codigo con permalinks (presiona y en GitHub para obtener una URL fijada a un commit). Un issue limpio y facil de escanear se clasifica mas rapido que un muro de texto.
Recuerda Quien Esta del Otro Lado
La mayoria de los mantenedores son voluntarios sin paga que trabajan en el proyecto en su tiempo libre, y eso moldea la etiqueta. No los menciones con @ ni les envies mensajes directos para exigir un arreglo, y no agregues comentarios de “alguna novedad?” que solo crean ruido. Saltate “+1” y “a mi tambien” por completo – agrega una reaccion 👍 al issue original para que los mantenedores puedan medir la demanda sin una avalancha de notificaciones. Comenta solo cuando tengas algo nuevo: otra reproduccion, un entorno diferente o una solucion temporal.
Y si sospechas de una vulnerabilidad de seguridad, no abras un issue publico en absoluto. Usa el reporte de seguridad privado del repositorio – normalmente una politica SECURITY.md o la pestana “Report a vulnerability” de GitHub – para que la falla no se difunda antes de ser parcheada.
La Formula Sigue Aplicando
Un gran issue en GitHub es simplemente la formula de Skip The Ask en el contexto de un desarrollador:
- Tu situacion – el proyecto, la version y el entorno que estas ejecutando
- Tu reporte o solicitud especifica – el bug o la funcionalidad exacta, en un titulo claro
- Detalles relevantes – un ejemplo minimo reproducible, el comportamiento esperado vs. el real y el error completo
Dale a los mantenedores un problema que puedan reproducir y habras hecho el 90% del trabajo para que se arregle.
Haces una pregunta de como hacer algo en vez de reportar un bug? Nuestra guia de Stack Overflow cubre ese caso. Para los principios universales detras de cada plataforma, consulta nuestra guia completa para hacer mejores preguntas en linea.