⚖️ El Juicio del Maestro: Pull Requests y Code Review

“Un ninja sabio no integra su código sin antes someterlo al escrutinio de sus pares. El ego es enemigo de la excelencia.” - Código de Honor del Desarrollador

🎯 La Filosofía del Pull Request

El Pull Request (PR) es el momento más importante de tu workflow:

  1. Propones cambios: “Terminé la feature, por favor revísenla”
  2. El equipo revisa: Comentarios, sugerencias, aprobaciones
  3. Iteras: Aplicas feedback, mejoras el código
  4. Se fusiona: Tu código pasa a producción

Un PR bien hecho es:

  • Una unidad lógica de trabajo (1 feature o 1 bugfix)
  • Auto-documentado (título, descripción, screenshots)
  • Revisable en <30 minutos
  • Testeado y funcional

📜 El Camino del Conocimiento

Parte 1: Crear un Pull Request Profesional

Flujo completo:

# 1. Asegúrate de estar actualizado
git switch main
git pull origin main

# 2. Crea rama para tu feature
git checkout -b feature/dark-mode

# 3. Trabaja, commitea
git add .
git commit -m "feat: implementar modo oscuro en navbar"
git commit -m "test: añadir tests para theme switcher"

# 4. Sube tu rama
git push origin feature/dark-mode

# 5. GitHub te muestra un link para crear PR
# O ve a: https://github.com/user/repo/compare/main...feature/dark-mode

Anatomía de un PR profesional:

Título:

feat: Añadir modo oscuro con toggle en navbar

Usa Conventional Commits:

  • feat: Nueva funcionalidad
  • fix: Corrección de bug
  • refactor: Cambio de código sin afectar funcionalidad
  • docs: Solo documentación
  • test: Añadir/corregir tests
  • chore: Tareas de mantenimiento (deps, configs)

Descripción del PR:

## 📝 Resumen
Implementa un toggle de modo oscuro que persiste la preferencia del usuario en localStorage.

## 🎯 Problema que Resuelve
Closes #42
Los usuarios solicitaban un tema oscuro para uso nocturno.

## ✨ Cambios Implementados
- ✅ Toggle en navbar (sol/luna icon)
- ✅ CSS variables para colores dinámicos
- ✅ Persistencia en localStorage
- ✅ Detección automática de preferencia del sistema (`prefers-color-scheme`)

## 🧪 Testing
- [ ] Probado en Chrome, Firefox, Safari
- [ ] Tests unitarios para `ThemeContext`
- [ ] Verificado que funciona con SSR (Next.js)

## 📸 Capturas de Pantalla
### Modo Claro
![Light mode](https://i.imgur.com/abc.webp)

### Modo Oscuro
![Dark mode](https://i.imgur.com/def.webp)

## 📚 Documentación
- Actualizado README con instrucciones de uso
- Añadido comentario en `ThemeContext.tsx`

## ⚠️ Breaking Changes
Ninguno. Es retrocompatible.

## 🔗 Referencias
- Diseño: [Figma](https://figma.com/file/xyz)
- Issue original: #42
- PR relacionado: #38 (implementó CSS variables)

## ✅ Checklist
- [x] El código compila sin errores
- [x] Los tests pasan (`npm test`)
- [x] Lint sin warnings (`npm run lint`)
- [x] Actualicé la documentación
- [x] Añadí tests para nueva funcionalidad

Elementos clave de la descripción:

  1. Resumen ejecutivo (1-2 líneas)
  2. Qué problema resuelve (vincula issue con Closes #X)
  3. Cambios técnicos (lista de lo que modificaste)
  4. Cómo probar (pasos para verificar)
  5. Evidencia visual (screenshots, GIFs, videos)
  6. Breaking changes (si los hay)

Parte 2: El Arte del Code Review

Como AUTOR del PR:

DO ✅:

  • Mantén PRs pequeños (<400 líneas de código)
  • Añade contexto en comentarios para código complejo
  • Responde a cada comentario (aunque sea con emoji ✅)
  • Agradece el feedback
  • Aplica sugerencias rápidamente

DON’T ❌:

  • No te pongas a la defensiva
  • No fuerces merge sin aprobaciones
  • No mezcles múltiples features en un PR
  • No subas código sin testear localmente

Como REVIEWER:

DO ✅:

  • Empieza con algo positivo (“Me gusta cómo manejaste X”)
  • Sé específico (“En línea 42, considera usar map en lugar de forEach”)
  • Pregunta antes de ordenar (“¿Consideraste usar un Set aquí?”)
  • Aprueba si es “suficientemente bueno” (no perfecto)
  • Usa emojis para suavizar críticas 😊

DON’T ❌:

  • No seas grosero o condescendiente
  • No pidas cambios sin explicar el porqué
  • No bloquees PRs por preferencias de estilo (usa linters)
  • No apruebes sin leer el código

Tipos de comentarios:

# 1. Pregunta (no bloqueante)
❓ ¿Consideraste usar `useMemo` aquí para optimizar renders?

# 2. Sugerencia (opcional)
💡 Sugerencia: Podrías extraer esto a un hook custom `useTheme()`

# 3. Cambio requerido (bloqueante)
🚨 Esto causa un memory leak. Debes limpiar el listener en el cleanup de useEffect.

# 4. Nitpick (estilo, no bloqueante)
🧹 Nitpick: Preferiría `isLoading` en lugar de `loading` para booleanos.

# 5. Aprobación con comentario
✅ LGTM! Solo un comentario menor arriba (no bloqueante).

Uso de GitHub Suggestions:

# Reviewer puede proponer cambios directos:
- const theme = localStorage.getItem('theme')
+ const theme = localStorage.getItem('theme') || 'light'

El autor puede aplicarlos con un click (“Commit suggestion”).

Parte 3: Flujo de Revisión Completo

Estado de un PR:

1. ⏳ Abierto (Open) → Esperando revisión
2. 👀 En revisión (Changes requested) → Autor debe aplicar feedback
3. ✅ Aprobado (Approved) → Listo para merge
4. 🎉 Fusionado (Merged) → Código en main
5. 🚫 Cerrado (Closed) → Rechazado o ya no aplica

Workflow típico:

# 1. Autor crea PR
git push origin feature/X

# 2. Reviewer comenta: "Cambia var a const en línea 10"

# 3. Autor aplica cambios
git add .
git commit -m "refactor: cambiar var a const según PR review"
git push origin feature/X
# GitHub actualiza el PR automáticamente

# 4. Reviewer aprueba

# 5. Autor o reviewer fusiona
# (Click en "Merge pull request" o desde CLI)
gh pr merge 42 --squash

Tipos de merge:

  1. Merge commit (default):

    git merge --no-ff feature/X
# Crea commit de merge, preserva historia completa

  2. Squash and merge (recomendado):

    git merge --squash feature/X
# Combina TODOS los commits de la rama en 1 solo
# Historia limpia en main

  3. Rebase and merge (para expertos):

    git rebase main
# Mueve commits de feature encima de main
# Historia lineal, sin merge commits

Comparación visual:

# Merge Commit:
main:     A---B---E---F (merge commit)
               \     /
feature:        C---D

# Squash:
main:     A---B---G (C+D combinados)

# Rebase:
main:     A---B---C'---D' (commits re-aplicados)

Configurar merge por defecto en GitHub:

Settings > General > Pull Requests

  • ✅ Allow squash merging (recomendado)
  • ❌ Allow merge commits (solo para proyectos open source grandes)
  • ❌ Allow rebase merging (solo si tu equipo lo domina)

Parte 4: Protecciones de Ramas

Branch Protection Rules previenen merges accidentales a main.

Settings > Branches > Add rule:

Branch name pattern: main

☑️ Require a pull request before merging
  ☑️ Require approvals (mínimo: 1)
  ☑️ Dismiss stale reviews when new commits are pushed
  
☑️ Require status checks to pass before merging
  ☑️ Require branches to be up to date before merging
  - Tests (CI)
  - Linter
  
☑️ Require conversation resolution before merging

☑️ Require linear history (evita merge commits)

☑️ Include administrators (ni siquiera admins pueden saltarse reglas)

Resultado:

  • ❌ No puedes hacer git push origin main directamente
  • ✅ Debes crear PR + obtener aprobación
  • ✅ Los tests deben pasar antes de merge

Parte 5: GitHub CLI para PRs

# Crear PR desde terminal
gh pr create --title "feat: dark mode" --body "Implementa tema oscuro"

# Crear PR interactivo (te pregunta título, descripción, etc.)
gh pr create

# Listar PRs abiertas
gh pr list

# Ver detalle de PR
gh pr view 42

# Checkout de un PR para probarlo localmente
gh pr checkout 42

# Añadir reviewer
gh pr edit 42 --add-reviewer @abraham,@maria

# Aprobar PR
gh pr review 42 --approve

# Solicitar cambios
gh pr review 42 --request-changes --body "Falta test en línea 10"

# Fusionar PR
gh pr merge 42 --squash --delete-branch

💡 Jutsu Secreto: PR Templates

Archivo .github/pull_request_template.md:

## 📝 Tipo de Cambio
- [ ] 🐛 Bug fix
- [ ] ✨ Nueva funcionalidad
- [ ] 💥 Breaking change
- [ ] 📚 Documentación

## 🎯 Descripción
<!-- Explica QUÉ cambiaste y POR QUÉ -->

## 🔗 Issue Relacionada
Closes #

## ✅ Checklist
- [ ] Mi código sigue el estilo del proyecto
- [ ] He realizado self-review de mi código
- [ ] He comentado partes complejas
- [ ] He actualizado la documentación
- [ ] Mis cambios no generan warnings
- [ ] He añadido tests que prueban mi fix/feature
- [ ] Tests unitarios pasan localmente
- [ ] Cambios dependientes ya fueron mergeados

## 📸 Screenshots (si aplica)
<!-- Añade imágenes o GIFs -->

Ahora cada PR se crea con esta plantilla pre-llenada.

🎯 Reto Ninja del Tema

Misión: Practicar flujo completo de PR

  1. Fork un proyecto público (ej: firstcontributions)
  2. Crea una rama add-tu-nombre
  3. Haz un cambio pequeño (añade tu nombre a Contributors.md)
  4. Push y abre PR siguiendo la plantilla profesional
  5. Simula una revisión:
    • Crea otro repo tuyo
    • Abre PR
    • Pide a un amigo que revise (o crea cuenta secundaria)
    • Aplica feedback
    • Aprueba y fusiona

Criterios de éxito:

  • ✅ Tu PR tiene título con conventional commit
  • ✅ La descripción tiene al menos 3 secciones
  • ✅ Añadiste una captura de pantalla (aunque sea del código)
  • ✅ Aplicaste al menos 1 sugerencia de reviewer
  • ✅ El PR fue fusionado exitosamente

📚 Recursos Adicionales

Siguiente Pergamino: 3.6 El Mapa de Estrategia - GitHub Projects (Kanban)

¿Hiciste tu primer PR? Comparte el link en Discord con #PrimerPR! 🎉🥷