Saltar a contenido

GIT_WORKFLOW.md

Flujo de Trabajo en Git

1. Principio

Nadie toca main directamente. Cada tarea nace en su propia rama, vive ahí, y se integra solo cuando fue revisada y aprobada. Los agentes IA actúan como copiloto: recuerdan cada paso y esperan confirmación del desarrollador antes de ejecutar cualquier acción git.

2. Rama principal

La rama principal del proyecto es main.

3. Nomenclatura de ramas

Prefijo Uso
feat/ Funcionalidad nueva
fix/ Corrección de bug
chore/ Tarea técnica sin impacto funcional (config, dependencias, docs)

Formato:

feat/nombre-descriptivo-de-la-tarea
fix/descripcion-del-bug
chore/actualizacion-de-dependencias

4. Ciclo de vida de una tarea

Paso 1 — Preparar la base

Antes de crear la rama, sincronizar main:

git checkout main
git pull origin main

Paso 2 — Crear la rama de trabajo

git checkout -b feat/nombre-de-la-tarea

Paso 3 — Desarrollo y commits frecuentes

No esperar a terminar todo para commitear. Commits frecuentes y descriptivos:

git add <archivo-modificado>
git commit -m "tipo(scope): descripción concisa del cambio"

Ejemplo:

feat(tickets): agregar filtro por fecha en el listado
fix(auth): corregir redirección post-login en mobile
chore(deps): actualizar dependencias de backend

Paso 4 — Subir la rama al remoto

Primera vez:

git push -u origin feat/nombre-de-la-tarea

Pushes posteriores:

git push

Paso 5 — Actualizar antes del PR

Si mientras trabajabas el equipo integró cambios en main:

git fetch origin
git rebase origin/main

Si hay conflictos durante el rebase:

  1. Identificar los archivos en conflicto.
  2. Resolver las diferencias en el editor.
  3. Marcar como resuelto: git add <archivo>
  4. Continuar: git rebase --continue

Paso 6 — Pull Request

  • Título: mismo formato que el commit (feat(scope): descripción).
  • Descripción: qué se hizo, cómo probar, consideraciones técnicas relevantes.
  • Reviewer: asignar a un integrante del equipo.
  • Estrategia de merge: usar Squash and Merge para que cada PR quede como un único commit en main con el mensaje del PR. Mantiene el historial limpio y trazable.
  • El PR se integra a main solo después de aprobación.

5. Archivos críticos — coordinación obligatoria

Antes de modificar cualquiera de estos archivos, comunicar la intención al equipo:

Archivo Motivo de riesgo
frontend/package.json Gestión de dependencias frontend
backend/config/settings.py Configuración compartida del sistema
backend/requirements.txt Librerías del backend
backend/conftest.py Configuración global de tests
docker-compose.yml Infraestructura base compartida
docker-compose.override.yml Configuración de desarrollo (hot reload, puertos)
docker-compose.prod.yml Configuración de producción (gunicorn, restart)

6. Cierre de sprint

Un sprint se considera cerrado cuando se cumplen todas estas condiciones en orden:

  1. Todas las ramas del sprint están mergeadas a main.
  2. El PR de cada tarea fue aprobado y pasó el PR_CHECKLIST.md.
  3. Se crea el tag del sprint en main:
git tag sprint-01
git push origin sprint-01
  1. Se registra el sprint cerrado en docs/sprints/SPRINT_XX.md con el resumen de lo completado, pendiente y decisiones tomadas. (Sistema de sprints a implementar — ver recomendaciones del kit.)
  2. Se actualiza docs/PROJECT_STATUS.md con el sprint activo y los módulos completados.

El agente sugiere el nombre del tag y los comandos. Espera confirmación del desarrollador antes de ejecutar.

7. Hotfix — Bug crítico en producción

Un hotfix aplica cuando hay un bug en producción que no puede esperar al próximo sprint.

Regla

Un hotfix resuelve solo lo que está roto. Nada más.

Proceso

Paso 1 — Sincronizar main:

git checkout main
git pull origin main

Paso 2 — Crear rama desde main:

git checkout -b fix/hotfix-descripcion-corta

Paso 3 — Implementar el fix mínimo

Solo los cambios necesarios para resolver el bug. Sin refactors ni mejoras adicionales.

Paso 4 — Commit:

git add <archivo>
git commit -m "fix(scope): descripción concisa del bug corregido"

Paso 5 — PR exprés

  • Mismo formato que cualquier PR.
  • Revisión prioritaria.
  • PR_CHECKLIST.md aplica sin excepciones — la urgencia no omite la validación.

Paso 6 — Merge y tag:

git tag hotfix-01
git push origin hotfix-01

Paso 7 — Actualizar estado:

Actualizar docs/PROJECT_STATUS.md con el hotfix aplicado.

8. Comportamiento obligatorio de los agentes IA

Los agentes IA actúan como copiloto git. Nunca ejecutan acciones git sin confirmación del desarrollador.

Cuándo y qué recordar

Momento Recordatorio del agente
Al iniciar una tarea Proponer nombre de rama y pedir confirmación para crearla
Al completar un bloque de trabajo Sugerir commit con mensaje ya redactado y esperar confirmación
Al tocar un archivo crítico Avisar antes de modificarlo y preguntar si se coordinó con el equipo
Al terminar la tarea Recordar hacer push y pedir confirmación
Después del push Recordar abrir el PR con título y descripción sugeridos
Al mergearse el PR de una tarea del sprint Actualizar docs/sprints/SPRINT-XX.md (tarea → CERRADA) y proponer commit directo a main — checkpoint de progreso del sprint
Al cerrarse el sprint Sugerir tag sprint-XX con los comandos listos y esperar confirmación
Ante bug crítico en producción Proponer rama fix/hotfix-descripcion desde main y esperar confirmación antes de cualquier acción

Formato de recordatorio

El agente debe ser explícito y concreto, nunca vago:

Git — Rama sugerida: feat/nombre-tarea
¿Creo la rama o la creás vos?

Git — Hay cambios listos para commitear.
Mensaje sugerido: feat(scope): descripción
¿Confirmás el commit?

Git — La tarea está completa.
¿Hacemos push de la rama `feat/nombre-tarea`?

Git — Aviso: vas a modificar `backend/requirements.txt` (archivo crítico).
¿Comunicaste la intención al equipo antes de continuar?

Git — PR de tarea mergeado. Actualizando tracker del sprint.
Tarea 3 → CERRADA en docs/sprints/SPRINT-00.md
Propongo commit directo a main:
  git add docs/sprints/SPRINT-00.md
  git commit -m "chore(sprint-00): tarea 3 cerrada — [nombre corto]"
¿Confirmás el checkpoint?

Git — Sprint 01 listo para cerrar. Todas las ramas mergeadas.
Comandos sugeridos:
  git tag sprint-01
  git push origin sprint-01
¿Confirmás el cierre del sprint?

Git — Cierre de sesión. Actualizados SPRINT-XX.md, PROJECT_STATUS.md y NEXT_ACTION.md.
Propongo commit directo a main:
  git add docs/sprints/SPRINT-XX.md docs/PROJECT_STATUS.md docs/NEXT_ACTION.md
  git commit -m "chore(sesion): actualizar estado del sprint y proyecto al cierre"
¿Confirmás el commit de cierre?

Lo que el agente nunca debe hacer

  • Hacer git push sin confirmación explícita.
  • Hacer commit sin que el desarrollador lo apruebe.
  • Mergear a main directamente.
  • Crear ramas sin proponer el nombre y esperar confirmación.
  • Ignorar que un archivo es crítico.
  • Crear tags de sprint o hotfix sin confirmación.

9. Regla de oro

Si el cambio toca main, permisos, infraestructura o archivos críticos, el agente avisa, espera y no actúa hasta recibir confirmación del desarrollador.