8bb46e4d08
- Move 6 non-standard folders to _archive/ - Update _MAP.md with standardized structure Standard: SIMCO-ESTANDAR-ORCHESTRATION v1.0.0 Level: SUB-CONSUMER Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
511 lines
15 KiB
Markdown
511 lines
15 KiB
Markdown
# SIMCO: GIT (Control de Versiones)
|
|
|
|
**Version:** 1.2.0
|
|
**Fecha:** 2026-01-16
|
|
**Aplica a:** TODO agente que modifica codigo o documentacion
|
|
**Prioridad:** OBLIGATORIA
|
|
|
|
---
|
|
|
|
## RESUMEN EJECUTIVO
|
|
|
|
> **Todo cambio en codigo o documentacion DEBE versionarse correctamente.**
|
|
> **Commits frecuentes, atomicos y descriptivos.**
|
|
> **PUSH OBLIGATORIO al finalizar cada tarea.**
|
|
> **FETCH OBLIGATORIO antes de verificar estado.**
|
|
> **Nunca perder trabajo por falta de commits o push.**
|
|
|
|
---
|
|
|
|
## REGLA CRITICA 1: FETCH ANTES DE OPERAR
|
|
|
|
```
|
|
╔══════════════════════════════════════════════════════════════════════════╗
|
|
║ ║
|
|
║ ANTES DE CUALQUIER VERIFICACION DE ESTADO GIT: ║
|
|
║ ║
|
|
║ 1. git fetch origin ║
|
|
║ → Obtener estado actual del remoto ║
|
|
║ ║
|
|
║ 2. git log HEAD..origin/main --oneline ║
|
|
║ → Si hay output = hay commits remotos que no tienes ║
|
|
║ ║
|
|
║ 3. Si hay commits remotos: ║
|
|
║ git pull --no-recurse-submodules ║
|
|
║ → Sincronizar antes de continuar ║
|
|
║ ║
|
|
║ 4. AHORA SI: git status ║
|
|
║ → Verificar estado local ║
|
|
║ ║
|
|
║ SIN FETCH = ESTADO INCOMPLETO ║
|
|
║ (Otro agente pudo hacer cambios en otra sesion) ║
|
|
║ ║
|
|
║ Referencia: INC-2026-01-16-001 ║
|
|
║ ║
|
|
╚══════════════════════════════════════════════════════════════════════════╝
|
|
```
|
|
|
|
### Secuencia Obligatoria de Verificacion
|
|
|
|
```bash
|
|
# SIEMPRE ejecutar en este orden:
|
|
git fetch origin
|
|
git log HEAD..origin/main --oneline # Si hay output, hacer pull
|
|
git pull --no-recurse-submodules # Solo si paso anterior tiene output
|
|
git status # Ahora si verificar estado local
|
|
```
|
|
|
|
---
|
|
|
|
## REGLA CRITICA 2: COMMIT + PUSH OBLIGATORIO
|
|
|
|
```
|
|
╔══════════════════════════════════════════════════════════════════════════╗
|
|
║ ║
|
|
║ TODA TAREA QUE CREA O MODIFICA ARCHIVOS DEBE TERMINAR CON: ║
|
|
║ ║
|
|
║ 1. git add . ║
|
|
║ 2. git commit -m "[ID] tipo: descripcion" ║
|
|
║ 3. git push origin {rama} ║
|
|
║ ║
|
|
║ SIN PUSH = TAREA INCOMPLETA ║
|
|
║ ║
|
|
║ En workspace con SUBMODULES: ║
|
|
║ - Commitear y push en CADA submodule afectado ║
|
|
║ - Luego commitear y push en workspace principal ║
|
|
║ ║
|
|
╚══════════════════════════════════════════════════════════════════════════╝
|
|
```
|
|
|
|
### Checklist Fin de Tarea (OBLIGATORIO)
|
|
|
|
```yaml
|
|
ANTES_de_reportar_tarea_completada:
|
|
- [ ] Todos los archivos creados/modificados estan guardados
|
|
- [ ] git status muestra archivos a commitear
|
|
- [ ] git add {archivos}
|
|
- [ ] git commit -m "[TAREA-ID] tipo: descripcion"
|
|
- [ ] git push origin {rama}
|
|
- [ ] Verificar: git status muestra "nothing to commit, working tree clean"
|
|
- [ ] Verificar: git log origin/main..HEAD muestra vacio (todo pusheado)
|
|
|
|
SI_hay_SUBMODULES:
|
|
- [ ] Repetir proceso en CADA submodule modificado
|
|
- [ ] Luego actualizar referencias en workspace principal
|
|
- [ ] Push final del workspace principal
|
|
```
|
|
|
|
### Secuencia para Workspace con Submodules
|
|
|
|
```bash
|
|
# 1. Commitear en cada submodule modificado
|
|
cd projects/{submodule}
|
|
git add .
|
|
git commit -m "[TAREA-ID] tipo: descripcion"
|
|
git push origin main
|
|
|
|
# 2. Repetir para cada submodule afectado
|
|
# ...
|
|
|
|
# 3. Actualizar workspace principal
|
|
cd /home/isem/workspace-v2
|
|
git add projects/{submodule} # Actualiza referencia del submodule
|
|
git commit -m "[WORKSPACE] chore: Update submodule references"
|
|
git push origin main
|
|
|
|
# 4. Verificar todo sincronizado
|
|
git status # Debe mostrar "clean"
|
|
```
|
|
|
|
---
|
|
|
|
## PRINCIPIOS FUNDAMENTALES
|
|
|
|
```
|
|
╔══════════════════════════════════════════════════════════════════════╗
|
|
║ ║
|
|
║ "Commitear temprano, commitear frecuentemente" ║
|
|
║ ║
|
|
║ Cada commit debe: ║
|
|
║ - Representar un cambio logico completo ║
|
|
║ - Ser funcional (no romper compilacion) ║
|
|
║ - Ser reversible sin afectar otros cambios ║
|
|
║ - Tener mensaje descriptivo con ID de tarea ║
|
|
║ ║
|
|
╚══════════════════════════════════════════════════════════════════════╝
|
|
```
|
|
|
|
---
|
|
|
|
## FRECUENCIA DE COMMITS
|
|
|
|
```yaml
|
|
OBLIGATORIO_commitear:
|
|
- Al finalizar cada fase (Analisis, Planeacion, Ejecucion)
|
|
- Al completar cada archivo significativo
|
|
- Cada 30-45 minutos de trabajo continuo
|
|
- Antes de lanzar subagentes
|
|
- Despues de validar trabajo de subagentes
|
|
- Antes de cambiar de tarea
|
|
- Cuando build + lint pasan
|
|
|
|
RAZON: "Minimizar perdida de trabajo en caso de error"
|
|
```
|
|
|
|
---
|
|
|
|
## FORMATO DE MENSAJE DE COMMIT
|
|
|
|
### Estructura Obligatoria
|
|
|
|
```
|
|
[{TAREA-ID}] {tipo}: {descripcion concisa}
|
|
|
|
{cuerpo opcional - descripcion detallada}
|
|
|
|
{footer opcional - referencias, breaking changes}
|
|
```
|
|
|
|
### Ejemplos Correctos
|
|
|
|
```bash
|
|
# Feature nueva
|
|
[DB-042] feat: Crear tabla projects con soporte PostGIS
|
|
|
|
# Bug fix
|
|
[BE-015] fix: Corregir validacion de codigo unico en ProjectService
|
|
|
|
# Refactor
|
|
[FE-008] refactor: Extraer componente ProjectCard de ProjectList
|
|
|
|
# Documentacion
|
|
[DB-042] docs: Actualizar DATABASE_INVENTORY con tabla projects
|
|
|
|
# Tests
|
|
[BE-015] test: Agregar tests unitarios para ProjectService
|
|
|
|
# Subtarea
|
|
[DB-042-SUB-001] feat: Implementar indices para tabla projects
|
|
```
|
|
|
|
### Ejemplos Incorrectos
|
|
|
|
```bash
|
|
# Sin ID de tarea
|
|
fix: Corregir bug
|
|
|
|
# Muy vago
|
|
[BE-015] update: Cambios varios
|
|
|
|
# Demasiado largo en primera linea
|
|
[DB-042] feat: Crear tabla projects con todas las columnas necesarias incluyendo soporte para PostGIS y configuracion de indices compuestos para optimizar queries
|
|
|
|
# Sin tipo
|
|
[FE-008] Mejorar componente
|
|
```
|
|
|
|
---
|
|
|
|
## TIPOS DE COMMITS
|
|
|
|
| Tipo | Uso | Ejemplo |
|
|
|------|-----|---------|
|
|
| `feat` | Nueva funcionalidad | `[DB-042] feat: Agregar soporte PostGIS` |
|
|
| `fix` | Correccion de bug | `[BE-015] fix: Resolver error en constraint` |
|
|
| `refactor` | Refactorizacion sin cambio funcional | `[FE-008] refactor: Mejorar estructura componentes` |
|
|
| `docs` | Solo documentacion | `[DB-042] docs: Actualizar README con schema` |
|
|
| `test` | Agregar/modificar tests | `[BE-015] test: Agregar tests para ProjectService` |
|
|
| `chore` | Tareas de mantenimiento | `[DB-042] chore: Actualizar dependencias` |
|
|
| `style` | Formato/estilo (sin cambio logico) | `[FE-008] style: Aplicar prettier` |
|
|
| `perf` | Mejora de performance | `[DB-042] perf: Agregar indice compuesto` |
|
|
| `build` | Cambios en build/deps | `[BE-015] build: Actualizar TypeORM a v0.3` |
|
|
| `ci` | Cambios en CI/CD | `[INFRA-001] ci: Agregar workflow de tests` |
|
|
|
|
---
|
|
|
|
## COMMITS ATOMICOS
|
|
|
|
### Que es un Commit Atomico
|
|
|
|
```yaml
|
|
atomico:
|
|
- Representa UN cambio logico completo
|
|
- Es funcional (build pasa)
|
|
- Es reversible individualmente
|
|
- No mezcla cambios no relacionados
|
|
|
|
NO_atomico:
|
|
- Multiples cambios no relacionados
|
|
- Trabajo incompleto (excepto WIP explicito)
|
|
- Mezcla de fix y feat
|
|
- Cambios en multiples features
|
|
```
|
|
|
|
### Ejemplo de Atomicidad
|
|
|
|
```bash
|
|
# CORRECTO - Commits atomicos separados
|
|
[DB-042] feat: Crear tabla projects
|
|
[DB-042] feat: Agregar indices a tabla projects
|
|
[DB-042] feat: Crear seeds para projects
|
|
[DB-042] docs: Actualizar inventario con tabla projects
|
|
|
|
# INCORRECTO - Un commit masivo
|
|
[DB-042] feat: Crear tabla projects con indices, seeds y actualizacion de inventario
|
|
```
|
|
|
|
---
|
|
|
|
## FLUJO DE TRABAJO GIT
|
|
|
|
### Antes de Empezar Tarea
|
|
|
|
```bash
|
|
# 1. Asegurar rama actualizada
|
|
git fetch origin
|
|
git pull origin main
|
|
|
|
# 2. Crear rama de trabajo (si aplica)
|
|
git checkout -b feature/{TAREA-ID}-descripcion-corta
|
|
|
|
# 3. Verificar estado limpio
|
|
git status
|
|
```
|
|
|
|
### Durante la Tarea
|
|
|
|
```bash
|
|
# 1. Hacer cambios
|
|
# ... editar archivos ...
|
|
|
|
# 2. Verificar que build pasa
|
|
npm run build
|
|
npm run lint
|
|
|
|
# 3. Agregar cambios
|
|
git add {archivos especificos}
|
|
# o para todos los cambios relacionados:
|
|
git add .
|
|
|
|
# 4. Commit con mensaje descriptivo
|
|
git commit -m "[TAREA-ID] tipo: descripcion"
|
|
|
|
# 5. Repetir para cada cambio logico
|
|
```
|
|
|
|
### Al Completar Tarea
|
|
|
|
```bash
|
|
# 1. Verificar historial
|
|
git log --oneline -5
|
|
|
|
# 2. Push a remoto
|
|
git push origin {rama}
|
|
|
|
# 3. Crear PR si aplica
|
|
gh pr create --title "[TAREA-ID] Descripcion" --body "..."
|
|
```
|
|
|
|
---
|
|
|
|
## CHECKLIST PRE-COMMIT
|
|
|
|
```yaml
|
|
ANTES_de_cada_commit:
|
|
- [ ] Build pasa sin errores
|
|
- [ ] Lint pasa sin errores criticos
|
|
- [ ] Tests pasan (si existen)
|
|
- [ ] Cambios son logicamente completos
|
|
- [ ] No hay archivos no deseados (node_modules, .env, etc.)
|
|
- [ ] Mensaje sigue formato correcto
|
|
|
|
VERIFICAR:
|
|
git status # Ver archivos modificados
|
|
git diff # Ver cambios en detalle
|
|
git diff --cached # Ver cambios staged
|
|
```
|
|
|
|
---
|
|
|
|
## ERRORES COMUNES
|
|
|
|
| Error | Consecuencia | Solucion |
|
|
|-------|--------------|----------|
|
|
| No commitear frecuentemente | Perdida de trabajo | Commit cada 30-45 min |
|
|
| Commits masivos | Dificil revertir | Commits atomicos |
|
|
| Mensajes vagos | Historial incomprensible | Seguir formato |
|
|
| Commit con build roto | Bloquea CI/CD | Verificar antes de commit |
|
|
| Olvidar ID de tarea | Perdida de trazabilidad | Siempre incluir [TAREA-ID] |
|
|
| Commitear secretos | Brecha de seguridad | Verificar .gitignore |
|
|
|
|
---
|
|
|
|
## ARCHIVOS A IGNORAR (.gitignore)
|
|
|
|
```yaml
|
|
SIEMPRE_ignorar:
|
|
- node_modules/
|
|
- .env
|
|
- .env.*
|
|
- dist/
|
|
- build/
|
|
- coverage/
|
|
- *.log
|
|
- .DS_Store
|
|
- *.tmp
|
|
- *.cache
|
|
|
|
NUNCA_commitear:
|
|
- Credenciales
|
|
- API keys
|
|
- Passwords
|
|
- Certificados privados
|
|
- Archivos de configuracion local
|
|
```
|
|
|
|
---
|
|
|
|
## RAMAS (BRANCHING)
|
|
|
|
### Convencion de Nombres
|
|
|
|
```yaml
|
|
ramas:
|
|
feature: feature/{TAREA-ID}-descripcion-corta
|
|
bugfix: bugfix/{TAREA-ID}-descripcion-corta
|
|
hotfix: hotfix/{TAREA-ID}-descripcion-corta
|
|
release: release/v{X.Y.Z}
|
|
|
|
ejemplos:
|
|
- feature/DB-042-crear-tabla-projects
|
|
- bugfix/BE-015-fix-validacion
|
|
- hotfix/SEC-001-fix-xss
|
|
- release/v2.1.0
|
|
```
|
|
|
|
### Flujo de Ramas
|
|
|
|
```
|
|
main (produccion)
|
|
│
|
|
├─── develop (desarrollo)
|
|
│ │
|
|
│ ├─── feature/DB-042-*
|
|
│ │ └── merge a develop
|
|
│ │
|
|
│ ├─── feature/BE-015-*
|
|
│ │ └── merge a develop
|
|
│ │
|
|
│ └── release/v2.1.0
|
|
│ └── merge a main + tag
|
|
│
|
|
└─── hotfix/SEC-001-*
|
|
└── merge a main + develop
|
|
```
|
|
|
|
---
|
|
|
|
## REVERTIR CAMBIOS
|
|
|
|
### Revertir Ultimo Commit (no pusheado)
|
|
|
|
```bash
|
|
# Mantener cambios en working directory
|
|
git reset --soft HEAD~1
|
|
|
|
# Descartar cambios completamente
|
|
git reset --hard HEAD~1
|
|
```
|
|
|
|
### Revertir Commit ya Pusheado
|
|
|
|
```bash
|
|
# Crear commit de reversion (seguro)
|
|
git revert {commit-hash}
|
|
git push
|
|
```
|
|
|
|
### Deshacer Cambios en Archivo
|
|
|
|
```bash
|
|
# Descartar cambios no staged
|
|
git checkout -- {archivo}
|
|
|
|
# Descartar cambios staged
|
|
git reset HEAD {archivo}
|
|
git checkout -- {archivo}
|
|
```
|
|
|
|
---
|
|
|
|
## SITUACIONES ESPECIALES
|
|
|
|
### Work in Progress (WIP)
|
|
|
|
```bash
|
|
# Cuando necesitas commitear trabajo incompleto
|
|
git commit -m "[TAREA-ID] WIP: descripcion de estado actual"
|
|
|
|
# Luego, completar y hacer commit final
|
|
# (opcional: squash commits WIP antes de PR)
|
|
```
|
|
|
|
### Antes de Lanzar Subagente
|
|
|
|
```bash
|
|
# SIEMPRE commitear antes de delegar
|
|
git add .
|
|
git commit -m "[TAREA-ID] chore: Estado antes de delegacion a {SubAgente}"
|
|
```
|
|
|
|
### Despues de Validar Subagente
|
|
|
|
```bash
|
|
# Commitear resultado de subagente
|
|
git add .
|
|
git commit -m "[TAREA-ID-SUB-XXX] tipo: Resultado de {SubAgente}"
|
|
```
|
|
|
|
---
|
|
|
|
## VALIDACION DE COMMITS
|
|
|
|
### Verificar Historial
|
|
|
|
```bash
|
|
# Ver ultimos commits
|
|
git log --oneline -10
|
|
|
|
# Ver commits de tarea especifica
|
|
git log --oneline --grep="DB-042"
|
|
|
|
# Ver cambios de un commit
|
|
git show {commit-hash}
|
|
```
|
|
|
|
### Verificar Formato de Mensaje
|
|
|
|
```yaml
|
|
formato_valido:
|
|
- Tiene [TAREA-ID] al inicio
|
|
- Tiene tipo valido (feat, fix, etc.)
|
|
- Descripcion concisa (<72 caracteres primera linea)
|
|
- No tiene errores de ortografia graves
|
|
|
|
verificar_manualmente:
|
|
git log --oneline -1
|
|
# Debe mostrar: {hash} [TAREA-ID] tipo: descripcion
|
|
```
|
|
|
|
---
|
|
|
|
## REFERENCIAS
|
|
|
|
- **Principio de Validacion:** @PRINCIPIOS/PRINCIPIO-VALIDACION-OBLIGATORIA.md
|
|
- **Documentar:** @SIMCO/SIMCO-DOCUMENTAR.md
|
|
- **Crear:** @SIMCO/SIMCO-CREAR.md
|
|
|
|
---
|
|
|
|
**Version:** 1.0.0 | **Sistema:** SIMCO | **Mantenido por:** Tech Lead
|