Git Team
Workflow
Guide

Flujo General del Equipo

Todo trabajo nace en Trello y termina en producción vía Pull Request. Ningún cambio al código llega a main sin haber pasado por este pipeline completo.

Integración con Trello

Trello es el punto de partida y cierre de todo trabajo. El tablero tiene columnas fijas que representan el ciclo de vida de cada tarea.

Columnas del tablero

Reglas de las tarjetas

• 01
  Cada tarjeta debe tener un responsable asignado. Sin asignado, nadie lo hace.
• 02
  El título de la tarjeta debe ser claro y accionable: "Agregar autenticación con Google", no "auth".
• 03
  La descripción debe incluir: qué se espera, criterios de aceptación y cualquier restricción técnica relevante.
• 04
  El ID de la tarjeta (ej: KY-42) debe usarse en el nombre del branch y en los commits.
• 05
  Al abrir el PR, se adjunta el link de la tarjeta Trello en la descripción del PR.
• 06
  Al mergear el PR, la tarjeta se mueve manualmente (o por automatización) a Done.

Naming convention de tarjetas

Etiquetas de Trello

Cada etiqueta responde una pregunta distinta de un vistazo. Si dos etiquetas dicen lo mismo, una sobra. Se usan en combinación: tipo + prioridad + estado especial.

Por tipo de trabajo — ¿qué es esto?

Por prioridad — ¿qué tan urgente es?

Por estado especial — ¿hay algo que me detenga?

Por módulo o contexto

Para proyectos con múltiples áreas o clientes en el mismo tablero, agregar etiquetas de contexto de color neutro:

Sistema recomendado — set mínimo

# Una tarjeta bien etiquetada combina máximo 3 etiquetas:
TIPO       → feature | bug | hotfix | refactor | chore
PRIORIDAD  → 🔥 crítico | alta prioridad | normal
ESTADO     → 🚧 bloqueado | ⏳ esperando cliente  (solo si aplica)
MÓDULO     → según el proyecto

# Ejemplo visual de una tarjeta:
🔵 feature · 🟠 alta prioridad · pagos
# → feature nueva, urgente, en el módulo de pagos

Lo que NO hacer con etiquetas

• ✗
  Más de 10 etiquetas en el sistema: el tablero se vuelve ilegible. Menos es más.
• ✗
  Etiquetas de estado como "en progreso": para eso están las columnas del tablero.
• ✗
  Etiquetas de persona como "eduardo": para eso existe la asignación de miembros.
• ✗
  Etiquetas redundantes con las columnas: si ya tienes la columna "En revisión", no necesitas la etiqueta en-review.

Checklists Base para Tarjetas

Cada tipo de tarjeta tiene su propio checklist. Se agrega al crear la tarjeta y sirve como contrato entre el dev y el equipo sobre qué significa "terminado".

✅ Checklist: Feature nueva

## Análisis
- [ ] Los criterios de aceptación están claros
- [ ] Se identificaron dependencias con otras tareas o módulos
- [ ] Se estimó el tiempo de desarrollo

## Desarrollo
- [ ] Branch creado con el ID de esta tarjeta (feature/KY-XX-nombre)
- [ ] El código sigue las convenciones del proyecto
- [ ] No hay console.log, comentarios de debug ni código muerto
- [ ] No se comitearon secrets ni archivos .env
- [ ] Manejo de errores implementado (no solo el happy path)

## Testing
- [ ] Probado localmente en todos los casos de uso
- [ ] Casos borde identificados y probados
- [ ] Tests unitarios agregados o actualizados (si aplica)

## Pull Request
- [ ] Rebase con develop hecho, sin conflictos
- [ ] CI pasa en verde
- [ ] PR abierto con link a esta tarjeta
- [ ] Screenshots adjuntos en el PR (si hay cambios visuales)
- [ ] Tarjeta movida a "En revisión"

🐛 Checklist: Bug fix

## Diagnóstico
- [ ] El bug está reproducido localmente
- [ ] Se identificó la causa raíz (no solo el síntoma)
- [ ] Se documentó cómo reproducirlo en la descripción de la tarjeta

## Desarrollo
- [ ] Branch creado: fix/KY-XX-descripcion
- [ ] El fix resuelve la causa raíz, no solo oculta el síntoma
- [ ] No se introdujeron cambios no relacionados al bug

## Validación
- [ ] El bug ya no se reproduce
- [ ] La funcionalidad existente no se rompió (regression check)
- [ ] Test agregado que cubre el caso del bug (para evitar regresión futura)

## Pull Request
- [ ] CI pasa en verde
- [ ] PR abierto con descripción clara del before/after
- [ ] Tarjeta movida a "En revisión"

🚨 Checklist: Hotfix en producción

## Respuesta rápida
- [ ] Impacto evaluado: ¿cuántos usuarios afecta? ¿pérdida de datos?
- [ ] Equipo notificado en el canal de comunicación
- [ ] Branch creado desde main: hotfix/KY-XX-descripcion

## Fix
- [ ] Solución mínima y quirúrgica (no refactorizar en un hotfix)
- [ ] Probado localmente

## Deploy
- [ ] PR aprobado (revisión express, mínimo 1 aprobación)
- [ ] Mergeado a main + tag de versión
- [ ] Mergeado de vuelta a develop
- [ ] Verificado en producción post-deploy
- [ ] Post-mortem breve documentado en la tarjeta (qué pasó, por qué, cómo evitarlo)

🔧 Checklist: Refactor / Deuda técnica

## Alcance
- [ ] Justificación documentada: ¿por qué refactorizar esto ahora?
- [ ] Alcance delimitado: qué entra y qué NO entra en este refactor
- [ ] Equipo avisado si se tocan módulos compartidos

## Desarrollo
- [ ] El comportamiento externo no cambió (misma API, mismos outputs)
- [ ] Tests existentes siguen pasando sin modificación
- [ ] No se mezclaron features ni fixes con el refactor

## Validación
- [ ] Code review con foco en que la lógica sea equivalente
- [ ] Performance no degradó (si aplica, benchmark antes/después)

🚀 Checklist: Release

## Pre-release
- [ ] Todas las tarjetas del sprint están en "Done"
- [ ] develop está estable (CI verde, sin conflictos)
- [ ] CHANGELOG actualizado con los cambios de esta versión
- [ ] Versión bumpeada según semver (MAJOR.MINOR.PATCH)

## Deploy
- [ ] Branch release/vX.X.X creado y testeado
- [ ] Mergeado a main con tag de versión
- [ ] Mergeado de vuelta a develop
- [ ] Deploy ejecutado y verificado en producción

## Post-release
- [ ] Cliente/stakeholder notificado
- [ ] Monitoreo activo las primeras 2 horas post-deploy
- [ ] Todas las tarjetas del release movidas a "Done"

Modelo de Ramas

Se usa un modelo simplificado de Git Flow adaptado a equipos pequeños. Solo existen dos ramas permanentes; el resto son temporales.

Ramas temporales

Crear una rama correctamente

# Siempre partir desde develop actualizado
git checkout develop
git pull origin develop

# Crear la rama con el ID de la tarjeta Trello
git checkout -b feature/KY-42-login-google

# Al terminar, sincronizar antes del PR
git fetch origin
git rebase origin/develop

Estándar de Commits

Se usa Conventional Commits con el ID de la tarjeta Trello obligatorio. Esto permite trazar cualquier cambio de código a su tarjeta original.

Formato

tipo(scope): descripción en imperativo [KY-42]

# Cuerpo opcional: explica el POR QUÉ, no el qué
# El qué ya lo dice el diff del código

Tipos de commit

Ejemplos correctos

feat(auth): agregar login con Google OAuth [KY-42]
fix(api): corregir error 500 en webhook de Wompi [KY-55]
refactor(pagos): extraer lógica de validación a servicio propio [KY-61]
docs: actualizar README con instrucciones de instalación [KY-30]
chore: actualizar dependencias a versiones estables

Ejemplos incorrectos

Reglas adicionales

• 01
  Un commit = un cambio lógico. No mezclar feature con fix en el mismo commit.
• 02
  Usar git add -p para staging interactivo. Evita el git add . irreflexivo.
• 03
  No commitear archivos .env, credenciales, tokens ni node_modules. Verificar el .gitignore antes del primer commit del proyecto.
• 04
  Si el commit rompe un build o test, se corrige en el mismo branch antes de abrir el PR. No se sube código roto.

Pull Requests

El PR es la unidad de entrega del equipo. Representa una tarea de Trello completada y lista para integrar.

Cuándo abrir un PR

• ✓
  La funcionalidad está completa y funcionando localmente.
• ✓
  Se hizo rebase con develop y no hay conflictos pendientes.
• ✓
  El CI (tests, lint) pasa en verde.
• ✓
  El código fue auto-revisado por el autor antes de subir.

Template del PR

## ¿Qué hace este PR?
Descripción clara y concisa del cambio.

## Trello
https://trello.com/c/xxxxx/KY-42-login-google

## Tipo de cambio
- [ ] Nueva feature
- [ ] Bug fix
- [ ] Refactor
- [ ] Documentación

## Checklist
- [ ] Mi código sigue las convenciones del proyecto
- [ ] Hice auto-review de mis cambios
- [ ] No hay secrets ni datos sensibles
- [ ] El CI pasa en verde
- [ ] Agregué/actualicé tests si aplica

## Screenshots (si aplica)

Tamaño del PR

Draft PRs

Si necesitas feedback temprano antes de terminar, abre un Draft PR. Esto comunica al equipo que el trabajo está en progreso y no está listo para merge. Convierte a PR normal cuando esté listo.

Code Review

El code review protege la calidad del código y distribuye el conocimiento del proyecto en el equipo. Nadie aprueba su propio PR.

Responsabilidades del reviewer

• 01
  Revisar en un plazo máximo de 24 horas hábiles desde que se asignó el PR.
• 02
  Verificar que el PR cumple con los criterios de aceptación de la tarjeta Trello.
• 03
  Probar el cambio localmente si es una feature crítica o si afecta partes sensibles del sistema.
• 04
  Comentar de forma constructiva. El objetivo es mejorar el código, no criticar al autor.

Tipos de comentario

Cómo dar feedback

El autor ante los comentarios

• 01
  Responder a cada comentario: aplicar el cambio, o explicar por qué no aplica.
• 02
  Marcar la conversación como "Resolved" una vez atendida.
• 03
  No tomar el feedback de forma personal. Es sobre el código, no sobre la persona.

Merge y Release

Estrategia de merge

Proceso de release

# 1. Crear rama de release desde develop
git checkout develop && git pull
git checkout -b release/v1.2.0

# 2. Actualizar versión y CHANGELOG
#    (actualiza package.json o version.txt según el proyecto)
git commit -m "chore: bump version to 1.2.0"

# 3. Mergear a main
git checkout main
git merge --no-ff release/v1.2.0

# 4. Taggear la versión
git tag -a v1.2.0 -m "Release v1.2.0"
git push origin main --tags

# 5. Mergear de vuelta a develop para sincronizar
git checkout develop
git merge --no-ff release/v1.2.0
git push origin develop

# 6. Eliminar la rama de release
git branch -d release/v1.2.0

Hotfixes en producción

# Los hotfix nacen desde main, no desde develop
git checkout main && git pull
git checkout -b hotfix/KY-99-crash-login

# Fix, commit, PR → aprobación rápida
# Merge a main + tag
# Luego sincronizar develop también
git checkout develop
git merge --no-ff hotfix/KY-99-crash-login

Versionado semántico

Las 10 Reglas de Oro

Estas reglas no son opcionales. Son el acuerdo del equipo.

• 01
  Nadie pushea directo a main ni a develop. Todo entra por PR con al menos una aprobación.
• 02
  Sin tarjeta Trello, no hay branch. Todo trabajo tiene su tarea correspondiente antes de escribir código.
• 03
  Ramas de vida corta. Máximo 3 días hábiles. Si tarda más, la tarea es demasiado grande.
• 04
  Commits atómicos y descriptivos. Un commit, un cambio lógico. Con el ID de Trello siempre.
• 05
  El CI es ley. Si el pipeline falla, el PR no se mergea. No hay excepciones.
• 06
  Nadie revisa su propio PR. El autor abre, otro aprueba.
• 07
  Reviews en máximo 24 horas hábiles. Un PR esperando revisión está bloqueando al equipo.
• 08
  Cero secrets en el repositorio. Variables de entorno, tokens, contraseñas — nunca en git.
• 09
  La tarjeta Trello sigue el estado real. Si estás en desarrollo, la tarjeta dice "En desarrollo". Sin excepciones.
• 10
  Comunicar antes de tocar código compartido. Si vas a refactorizar un módulo que otros usan, avisar en el canal del equipo primero.

Herramientas del Equipo

Git hooks con Husky

# Instalar
npm install --save-dev husky commitlint @commitlint/config-conventional

# commitlint.config.js
module.exports = { extends: ['@commitlint/config-conventional'] }

# Hook: rechaza commits mal formateados automáticamente

Alias útiles de Git

git config --global alias.lg "log --oneline --graph --all --decorate"
git config --global alias.st "status -sb"
git config --global alias.undo "reset --soft HEAD~1"
git config --global alias.save "stash push -m"

.gitignore base

# Entorno
.env
.env.local
.env.*.local

# Dependencias
node_modules/
vendor/

# Builds
dist/
build/
*.jar
*.class

# IDE
.idea/
.vscode/
*.iml

# OS
.DS_Store
Thumbs.db