Todos los cursos > Informática ( TI ) > Herramientas de TI ::

Gestión de trabajo en GitHub: issues, seguimiento y comunicación técnica

Capítulo 11

Tiempo estimado de lectura: 8 minutos

¿Qué es un issue en GitHub y para qué sirve?

Un issue es una unidad de trabajo y comunicación dentro de un repositorio: sirve para reportar bugs, proponer mejoras, hacer preguntas técnicas y dividir trabajo en tareas accionables. Un issue bien escrito reduce ambigüedades, acelera el diagnóstico y deja un rastro claro de decisiones.

Bug: algo no funciona como debería (regresión, error, comportamiento inesperado).
Mejora: optimización, refactor, UX, rendimiento, accesibilidad.
Tarea: trabajo concreto y verificable (p. ej., “Agregar validación de email en el formulario”).
Pregunta técnica: aclarar requisitos o decisiones (p. ej., “¿Este endpoint debe ser idempotente?”).

Guía práctica: crear un issue útil paso a paso

1) Elige el tipo de issue y escribe un título accionable

El título debe permitir entender el problema sin abrir el issue. Evita títulos vagos como “No funciona”. Prefiere estructura [Área] Resultado o Bug: ....

Bug: login falla con contraseña válida cuando el usuario tiene 2FA
[UI] El botón Guardar no se deshabilita durante el envío
Mejora: cachear respuesta de /products por 60s

2) Describe el contexto y el impacto

En 2–4 frases, explica qué estabas intentando hacer y por qué importa. Esto ayuda a priorizar y a entender el alcance.

Ejemplo: “Al intentar iniciar sesión con 2FA activado, el sistema devuelve 500. Esto bloquea a usuarios con 2FA y afecta el flujo principal de acceso.”

3) Añade pasos para reproducir (reproducibilidad)

Escribe pasos numerados, mínimos y deterministas. Si depende de datos, incluye un ejemplo concreto.

Continúa en nuestra aplicación.

Escuche el audio con la pantalla apagada.
Obtenga un certificado al finalizar.
¡Más de 5000 cursos para que explores!

O continúa leyendo más abajo...

Descargar la aplicación

Pasos para reproducir: 1. Crear usuario con 2FA activado (usar usuario: qa-2fa@example.com) 2. Ir a /login 3. Ingresar credenciales válidas 4. Confirmar código 2FA 5. Observar error

4) Especifica comportamiento esperado vs observado

Separar “esperado” y “observado” evita discusiones y acelera el triage.

Comportamiento esperado: - El usuario inicia sesión y es redirigido a /dashboard Comportamiento observado: - Respuesta 500 - En UI aparece: "Algo salió mal"

5) Indica el entorno (dónde ocurre)

Incluye la información mínima para reproducir en condiciones similares.

App: versión/release o hash si aplica
Entorno: producción/staging/local
Navegador/OS: si es frontend
API/DB: si es backend (p. ej., versión de Node/Python, motor de DB)

Entorno: - App: v1.8.2 - Entorno: staging - OS: macOS 14.3 - Navegador: Chrome 121 - Backend: Node 20.11 - DB: Postgres 15

6) Adjunta evidencia (sin ruido)

Incluye solo lo que ayude a diagnosticar: logs relevantes, capturas, payloads, IDs de request. Si hay datos sensibles, anonímizalos.

Fragmento de log con timestamp y correlación
Captura de pantalla o video corto
Request/response (headers importantes, status code)

Evidencia: - Request ID: 9f2c... - Log: "TypeError: cannot read property 'token' of undefined" en AuthService.ts:88

Plantillas listas para copiar (bugs, mejoras y tareas)

Plantilla: reporte de bug

## Resumen Breve descripción del problema y el impacto. ## Pasos para reproducir 1. ... 2. ... 3. ... ## Comportamiento esperado - ... ## Comportamiento observado - ... ## Entorno - App: - Entorno: - OS/Navegador: - Otros: ## Evidencia - Logs: - Capturas: - Request ID / enlaces: ## Notas adicionales (opcional) Hipótesis, frecuencia, workarounds conocidos.

Plantilla: propuesta de mejora

## Problema ¿Qué duele hoy? ¿Qué limitación existe? ## Propuesta ¿Qué cambiarías? Describe la solución a alto nivel. ## Alternativas consideradas Otras opciones y por qué no. ## Criterios de aceptación - [ ] ... - [ ] ... ## Impacto y riesgos Rendimiento, compatibilidad, migraciones, seguridad. ## Evidencia/Contexto Links, métricas, ejemplos.

Plantilla: tarea accionable

## Objetivo Qué se va a entregar. ## Alcance - Incluye: ... - Excluye: ... ## Checklist - [ ] ... - [ ] ... ## Criterios de aceptación Condiciones verificables para dar por terminado. ## Dependencias Issues/PRs relacionados.

Dividir trabajo en tareas accionables (sin perder trazabilidad)

Cuando un issue es grande, conviértelo en un “issue padre” con checklist y crea issues hijos para cada parte. Esto permite avanzar en paralelo y revisar por partes.

Ejemplo: issue padre con subtareas

Título: Mejora: reducir tiempo de carga del listado de productos Descripción: Objetivo: bajar TTFB de 800ms a <300ms en /products. Checklist: - [ ] #123 Cache de /products por 60s - [ ] #124 Índices en tabla products (name, category_id) - [ ] #125 Medición: dashboard con p95/p99 - [ ] #126 Ajustar paginación y límites por defecto

En GitHub, al escribir #123 se crea un enlace automático al issue. Mantén cada issue hijo con criterios de aceptación claros.

Etiquetado, asignación y priorización operativa

Etiquetas (labels) recomendadas

Las etiquetas ayudan a filtrar y a entender el estado sin leer todo.

Categoría	Ejemplos	Uso
Tipo	`bug`, `enhancement`, `task`, `question`	Clasificar rápidamente
Área	`frontend`, `backend`, `docs`, `api`, `ci`	Enrutar al equipo correcto
Severidad	`sev:critical`, `sev:high`, `sev:medium`, `sev:low`	Impacto técnico/usuario
Prioridad operativa	`prio:p0`, `prio:p1`, `prio:p2`	Orden de atención
Estado	`needs-triage`, `needs-info`, `blocked`, `ready`	Visibilidad del flujo

Buenas prácticas:

Usa pocas etiquetas, pero consistentes (mejor 12 bien definidas que 60 ambiguas).
Evita duplicar significado (p. ej., urgent y prio:p0 a la vez).
Define un criterio para blocked (siempre indicar por qué y por quién/qué).

Asignación (assignees) y responsables

Asigna el issue cuando haya una persona responsable de moverlo (aunque no haga todo).
Si aún no se sabe quién lo hará, usa needs-triage y evita asignar “por compromiso”.
Cuando pidas información al autor, cambia a needs-info y escribe preguntas concretas.

Prioridad operativa (sin planificación académica)

Prioriza con señales observables:

Impacto: ¿bloquea una funcionalidad clave?, ¿afecta a muchos usuarios?
Riesgo: ¿hay pérdida de datos?, ¿seguridad?, ¿caídas?
Urgencia: ¿hay un incidente activo?, ¿hay workaround?
Esfuerzo: si dos tareas tienen impacto similar, empieza por la de menor esfuerzo.

Relacionar issues con commits y pull requests (referencias y autocierre)

GitHub detecta referencias en texto usando #<número>. Puedes enlazar issues desde commits, descripciones de PR y comentarios para mantener trazabilidad.

Referenciar un issue desde un commit

En el mensaje del commit, incluye el número del issue:

git commit -m "Fix: manejar null token en AuthService (#87)"

Esto crea un enlace desde el issue al commit (y viceversa) en GitHub.

Referenciar un issue desde un pull request

En la descripción del PR, agrega una sección “Relacionado” y usa palabras clave de autocierre cuando corresponda.

## Relacionado - Closes #87 - Related to #90 ## Qué cambia - Evita null dereference en AuthService - Agrega test para usuario con 2FA

Palabras clave comunes para autocerrar (en el texto del PR): close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved + #ID.

Cerrar issues con mensajes claros

Si cierras manualmente un issue (sin autocierre), deja un comentario final que explique el motivo y cómo verificar.

Cierre por solución: “Corregido en PR #142. Verificar en staging: login con usuario qa-2fa@example.com y código válido redirige a /dashboard.”
Cierre por duplicado: “Duplicado de #155. Continuamos el seguimiento allí para centralizar evidencia.”
Cierre por no reproducible: “No se pudo reproducir con App v1.8.2 en staging. Necesitamos: request ID y hora aproximada. Reabrir cuando haya evidencia.”

Comunicación técnica concisa para reducir ambigüedades

Reglas prácticas de redacción

Una idea por párrafo y frases cortas.
Evita adjetivos vagos (“a veces”, “raro”, “lento”) y reemplaza por datos (“3/10 intentos”, “p95=1.2s”).
Define términos si pueden interpretarse distinto (“usuario nuevo” = sin compras previas).
Pregunta con opciones cuando haya decisiones (“¿A o B?”) para acelerar respuestas.

Ejemplos de comentarios útiles (y su versión mejorada)

Ambiguo	Conciso y verificable
“Falla el login.”	“En staging, login con 2FA devuelve 500. Pasos: 1) /login 2) credenciales válidas 3) código 2FA. Esperado: /dashboard. Observado: 500. Request ID: 9f2c...”
“Está lento.”	“/products p95 pasó de 280ms a 820ms desde v1.8.1. Afecta a usuarios anónimos. Evidencia: métrica p95 y log de tiempos.”
“Creo que es un problema de la API.”	“La UI recibe 502 del endpoint GET /api/orders. Respuesta del proxy: upstream timeout. No ocurre en local. ¿Hay cambios recientes en rate limit?”

Triage rápido: qué hacer cuando llega un issue nuevo

Confirmar tipo (bug/mejora/tarea) y aplicar etiquetas mínimas: tipo + área + estado (needs-triage o ready).
Buscar duplicados por palabras clave y cerrar/enlazar si corresponde.
Pedir información faltante con una lista corta de preguntas: “¿versión?, ¿pasos?, ¿evidencia?”
Definir siguiente acción: reproducir, investigar, proponer solución, dividir en subtareas.

Ejemplo de solicitud de información (plantilla)

Gracias por el reporte. Para poder reproducir, ¿puedes agregar? - Versión de la app y entorno (staging/prod/local) - Pasos exactos (1..n) - Comportamiento esperado vs observado - Evidencia: request ID o fragmento de log con hora aproximada

Ahora responde el ejercicio sobre el contenido:

Para que un issue de bug sea fácil de diagnosticar y hacer triage, ¿qué información es más importante incluir en la descripción?

¡Tienes razón! Felicitaciones, ahora pasa a la página siguiente.

¡Tú error! Inténtalo de nuevo.

Un buen issue reduce ambigüedades si permite reproducir y comparar lo esperado con lo observado, indicando además el entorno y evidencia útil (logs, request ID). Eso acelera el triage y el diagnóstico.