📋 La Taberna de las Misiones: Issues, Labels y Milestones

“El general sabio planifica la guerra antes de desenfundar su espada. En GitHub, las Issues son tu mapa de batalla.” - Arte de la Gestión

🎯 La Filosofía del Tablero de Misiones

Antes de escribir código, un equipo profesional define qué construir. Las Issues son el sistema de tareas de GitHub:

  • Bug reports: “El botón de login no funciona en Safari”
  • Feature requests: “Añadir modo oscuro”
  • Preguntas: “¿Cómo configurar variables de entorno?”
  • Mejoras: “Optimizar consultas SQL en /api/users”

Los Labels clasifican misiones por tipo (bug, enhancement, documentation). Los Milestones agrupan issues hacia un objetivo común (v1.0, Sprint 3).

📜 El Camino del Conocimiento

Parte 1: Crear y Gestionar Issues

Crear una issue desde la interfaz web:

  1. Ve a tu repositorio en GitHub
  2. Click en la pestaña “Issues”
  3. Click “New issue”
  4. Llena el formulario:
    • Título: Descriptivo y breve (Login redirige a 404)
    • Descripción: Contexto, pasos para reproducir, comportamiento esperado
    • Assignees: ¿Quién trabajará en esto?
    • Labels: bug, high priority
    • Projects/Milestone: Vincúlala a un objetivo

Anatomía de una issue profesional:

## 🐛 Descripción del Bug
Al hacer clic en "Iniciar Sesión" con credenciales válidas, la app redirige a una página 404 en lugar del dashboard.

## 🔄 Pasos para Reproducir
1. Ir a `https://app.ejemplo.com/login`
2. Ingresar email: `ninja@dojo.com`, password: `secreto123`
3. Hacer clic en "Iniciar Sesión"
4. **Resultado:** Página 404
5. **Esperado:** Dashboard en `/dashboard`

## 🌍 Entorno
- **Navegador:** Chrome 122.0 (también falla en Firefox)
- **SO:** macOS Sonoma 14.2
- **Versión de la app:** v2.1.0

## 📸 Capturas de Pantalla
![Error 404](https://i.imgur.com/abc123.webp)

## 💡 Posible Solución
Revisar la ruta en `src/routes/auth.js`. Puede ser un typo en el redirect.

## ✅ Checklist
- [ ] Bug reproducido en dev
- [ ] Fix implementado
- [ ] Tests unitarios añadidos
- [ ] Probado en Chrome/Firefox/Safari

Elementos clave de una buena issue:

  1. Título accionable: “Arreglar redirección de login” (no “Login no anda”)
  2. Contexto suficiente: Alguien que NO conoce el proyecto debe entenderlo
  3. Pasos reproducibles: Si es bug, ¿cómo lo provoco?
  4. Criterios de aceptación: ¿Cuándo la issue está “completa”?
  5. Referencias: Links a PRs relacionados, documentación, diseños

Crear issues desde CLI (GitHub CLI):

# Instalar GitHub CLI (si no lo tienes)
brew install gh          # macOS
# O descarga desde: https://cli.github.com

# Autenticarte
gh auth login

# Crear issue interactivamente
gh issue create

# Crear issue con todos los datos de una vez
gh issue create \
  --title "Añadir modo oscuro" \
  --body "Los usuarios piden un tema dark. Prioridad alta." \
  --label "enhancement,high priority" \
  --assignee @me

# Listar issues abiertas
gh issue list

# Ver detalle de una issue
gh issue view 42

# Cerrar issue
gh issue close 42

Parte 2: Labels - El Sistema de Clasificación

Los labels son etiquetas de color que clasifican issues por tipo, prioridad, área del proyecto.

Labels por defecto de GitHub:

LabelColorUso
bug🔴 RojoErrores de código
enhancement🟢 VerdeNuevas funcionalidades
documentation🔵 AzulMejorar docs
good first issue🟣 MoradoPara contribuidores nuevos
help wanted🟡 AmarilloSe busca colaboración
wontfix⚫ GrisNo se implementará
duplicate⚪ BlancoYa existe otra issue

Crear labels personalizados:

Desde la interfaz:

  1. Ir a Issues > Labels
  2. Click “New label”
  3. Nombre: backend, Color: #0e8a16, Descripción: Server-side code

Desde CLI:

# Crear label
gh label create "backend" --color 0e8a16 --description "Server-side code"

# Listar labels
gh label list

# Añadir label a una issue
gh issue edit 42 --add-label "backend,bug"

Sistema de labels profesional (ejemplo):

Por tipo:

  • bug 🔴 - Algo no funciona
  • feature 🟢 - Nueva funcionalidad
  • refactor 🔵 - Mejorar código sin cambiar funcionalidad
  • docs 📘 - Documentación
  • tests 🧪 - Testing

Por prioridad:

  • p0-critical 🚨 - Bloquea producción
  • p1-high ⚠️ - Importante, siguiente sprint
  • p2-medium 📌 - Deseable
  • p3-low 💤 - Backlog

Por área:

  • frontend 🎨 - UI/UX
  • backend ⚙️ - API/Base de datos
  • devops 🐳 - CI/CD, Docker, deploys
  • security 🔒 - Vulnerabilidades

Estados:

  • in-progress 🏗️ - Alguien trabajando
  • blocked 🚧 - Esperando dependencia
  • ready-for-review 👀 - PR abierto, pendiente aprobación

Combinación de labels en acción:

Issue #47: "Endpoint /api/users devuelve 500"
Labels: bug, backend, p0-critical, in-progress
Assignee: @abraham
Milestone: Sprint 5

Parte 3: Milestones - Hitos del Proyecto

Un Milestone agrupa issues relacionadas hacia un objetivo común.

Ejemplos de milestones:

  • v1.0 Launch - Issues que DEBEN estar en el primer release
  • Sprint 3 - Trabajo de esta iteración de 2 semanas
  • Q1 2026 - Objetivos del trimestre
  • Performance Improvements - Tema específico

Crear milestone:

Desde GitHub:

  1. Issues > Milestones > New milestone
  2. Title: v1.0 - MVP Launch
  3. Due date: 2026-05-01
  4. Description: 
    Primer release público. Debe incluir:
- Autenticación completa
- CRUD de tareas
- Dashboard básico

Desde CLI:

# Crear milestone
gh api repos/:owner/:repo/milestones \
  -f title='v1.0 Launch' \
  -f description='Primer release público' \
  -f due_on='2026-05-01T00:00:00Z'

# Listar milestones
gh api repos/:owner/:repo/milestones

Vincular issue a milestone:

# Desde la UI: Al crear/editar issue, selecciona Milestone en sidebar

# Desde CLI:
gh issue edit 42 --milestone "v1.0 Launch"

Dashboard de progreso:

GitHub muestra automáticamente:

  • X issues cerradas / Y totales
  • Barra de progreso visual
  • Tiempo restante hasta due date

Ejemplo:

v1.0 Launch
15 / 23 issues cerradas (65%)
📅 Due on May 1, 2026 (23 days left)

Parte 4: Workflows Avanzados

Issue Templates:

Crea plantillas predefinidas para bugs, features, etc.

# Estructura de carpeta
.github/
└── ISSUE_TEMPLATE/
    ├── bug_report.md
    └── feature_request.md

Archivo .github/ISSUE_TEMPLATE/bug_report.md:

---
name: 🐛 Bug Report
about: Reportar un error o comportamiento inesperado
title: '[BUG] '
labels: bug
assignees: ''
---

## Descripción del Bug
Una descripción clara del problema.

## Pasos para Reproducir
1. Ir a '...'
2. Hacer clic en '...'
3. Scroll hasta '...'
4. Ver error

## Comportamiento Esperado
Lo que debería pasar.

## Capturas de Pantalla
Si aplica, añade capturas.

## Entorno
- Navegador: [ej. Chrome 122]
- SO: [ej. macOS 14.2]
- Versión: [ej. v2.1.0]

Ahora cuando creen issues, verán botones para elegir plantilla.

Referenciar issues en commits:

# Mencionar issue en commit (crea link automático)
git commit -m "fix: corregir login redirect (#42)"

# Cerrar issue automáticamente al fusionar
git commit -m "fix: resolver bug de login

Closes #42"
# Cuando este commit llegue a main, issue #42 se cierra sola

Palabras clave que cierran issues:

  • Closes #42
  • Fixes #42
  • Resolves #42

Issue references cruzadas:

# En issue #50:
Este bug es similar a #42, pero afecta a Firefox.
Depende de #48 (añadir tests).

GitHub crea links automáticos y muestra referencias en el timeline.

💡 Jutsu Secreto: Automatización con GitHub Actions

Ejemplo: Auto-etiquetar issues según palabras clave

# .github/workflows/label-issues.yml
name: Auto Label Issues

on:
  issues:
    types: [opened]

jobs:
  label:
    runs-on: ubuntu-latest
    steps:
      - name: Label bug
        if: contains(github.event.issue.title, 'bug') || contains(github.event.issue.body, 'error')
        run: gh issue edit ${{ github.event.issue.number }} --add-label "bug"
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      
      - name: Label feature
        if: contains(github.event.issue.body, 'feature request')
        run: gh issue edit ${{ github.event.issue.number }} --add-label "enhancement"
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Otras automatizaciones útiles:

  • Cerrar issues inactivas después de 30 días
  • Asignar automáticamente según área del código
  • Notificar en Slack cuando se crea issue con label p0-critical

🎯 Reto Ninja del Tema

Misión: Planificar un proyecto completo con Issues

  1. Crea un repositorio llamado task-master-ninja
  2. Crea 3 milestones:
    • v0.1 - Setup (Due: en 1 semana)
    • v0.2 - Core Features (Due: en 2 semanas)
    • v1.0 - Launch (Due: en 1 mes)
  3. Crea 10 issues distribuidas en los milestones:
    • 3 bug (issues #1, #2, #3)
    • 4 enhancement (#4, #5, #6, #7)
    • 2 documentation (#8, #9)
    • 1 good first issue (#10)
  4. Crea labels personalizados:
    • frontend (color: #ff6b6b)
    • backend (color: #4ecdc4)
    • high priority (color: #ff0000)
  5. Asigna labels apropiados a cada issue
  6. Cierra 3 issues con commits que usen Closes #X

Criterios de éxito:

  • ✅ Tienes al menos 3 milestones creados
  • ✅ Cada milestone tiene issues asignadas
  • ✅ Usas al menos 5 labels diferentes
  • ✅ Al menos 1 issue se cerró automáticamente con commit

📚 Recursos Adicionales

Siguiente Pergamino: 3.5 El Juicio del Maestro - Pull Requests y Code Review

¿Organizaste tu proyecto? Comparte un screenshot de tus milestones en Discord con #TabernaNinja! 📋🥷