Documentación del Sistema

Appearance

Git Workflow — Sistema Bautista ​

Flujo de trabajo estándar basado en Git Flow con commits convencionales, squash merge y versionado semántico.

Estructura de Ramas ​

master (producción)
  ├─ hotfix/* ──────────────> master + develop
  │
develop (integración)
  ├─ feature/* ────────────> develop  (squash merge)
  ├─ bugfix/*  ────────────> develop  (squash merge)
  └─ release/* ────────────> master + develop (no-ff)

Tabla de ramas ​

RamaBaseMerge haciaEstrategiaEjemplo
feature/*developdevelopSquash mergefeature/nombre-descriptivo
bugfix/*developdevelopSquash mergebugfix/descripcion-bug
hotfix/*mastermaster + developNo-FF mergehotfix/problema-critico
release/*developmaster + developNo-FF mergerelease/v1.2.0

Árbol de Decisión ​

¿Fix urgente en producción?
  → hotfix/* desde master

¿Nueva funcionalidad?
  → feature/* desde develop

¿Fix de bug en desarrollo?
  → bugfix/* desde develop

¿Preparar release?
  → release/* desde develop

¿Listo para mergear?
  → Squash merge (features/bugfixes) o No-FF (releases/hotfixes)

Flujo de Trabajo por Tipo de Rama ​

feature/* — Nueva funcionalidad ​

bash
# 1. Crear rama
git checkout develop
git pull origin develop
git checkout -b feature/nombre-descriptivo

# 2. Trabajar con commits atómicos
git commit -m "feature/ventas: agregar servicio de timbrado"

# 3. Rebase antes de mergear
git fetch origin
git rebase origin/develop

# 4. Squash merge a develop
git checkout develop
git merge --squash feature/nombre-descriptivo
git commit -m "feature/ventas: implementar facturación electrónica

- Agregado servicio de timbrado
- Generación de XML y validación CAE"
git push origin develop

# 5. Limpiar
git branch -d feature/nombre-descriptivo

bugfix/* — Corrección de bug en desarrollo ​

bash
git checkout develop
git pull origin develop
git checkout -b bugfix/descripcion-bug

# Fix + commit
git commit -m "fix/stock: corregir cálculo de inventario"

# Squash merge (mismo flujo que feature)
git checkout develop
git merge --squash bugfix/descripcion-bug
git commit -m "fix/stock: corregir cálculo de inventario"
git push origin develop
git branch -d bugfix/descripcion-bug

hotfix/* — Fix urgente en producción ​

bash
git checkout master
git pull origin master
git checkout -b hotfix/v1.2.1

# Fix + commit
git commit -m "hotfix/auth: resolver vulnerabilidad XSS"

# Actualizar CHANGELOG
git commit -m "docs: actualizar CHANGELOG con hotfix v1.2.1"

# Merge a master
git checkout master
git merge --no-ff hotfix/v1.2.1
git tag -a v1.2.1 -m "Hotfix 1.2.1"
git push origin master --tags

# Merge a develop
git checkout develop
git merge --no-ff hotfix/v1.2.1
git push origin develop

git branch -d hotfix/v1.2.1

release/* — Preparación de versión ​

bash
git checkout develop
git pull origin develop
git checkout -b release/v1.2.0

# Actualizar archivos de versión
# - composer.json  (backend)
# - config/app.php (backend)
# - package.json   (frontend)
# - CHANGELOG.md

git add composer.json config/app.php package.json CHANGELOG.md
git commit -m "chore: bump version to v1.2.0"

# Merge a master
git checkout master
git merge --no-ff release/v1.2.0
git tag -a v1.2.0 -m "Version 1.2.0"
git push origin master --tags

# Merge a develop
git checkout develop
git merge --no-ff release/v1.2.0
git push origin develop

git branch -d release/v1.2.0

Estrategias de Merge ​

Squash merge (features y bugfixes) ​

Crea historial lineal: un commit por funcionalidad en develop.

bash
git merge --squash feature/mi-feature
git commit -m "feature/ventas: implementar facturación electrónica"

No-FF merge (releases y hotfixes) ​

Preserva historial de la rama para auditoría.

bash
git merge --no-ff release/v1.2.0

Convención de Commits ​

Formato (ESTRICTO) ​

tipo/área: descripción breve

[cuerpo opcional con contexto]

Reglas absolutas:

  • NO footers — nunca Co-Authored-By, Closes, ni ningún footer
  • Máximo 72 caracteres en la línea de asunto
  • Imperativo, minúsculas, sin punto — "agregar" no "agregado" ni "Agregar."
  • Atómico — un cambio lógico por commit
  • Español — descripción siempre en español

Comando HEREDOC (siempre usar para evitar errores de formato):

bash
git commit -m "$(cat <<'EOF'
tipo/área: descripción breve

Cuerpo opcional con contexto adicional.
EOF
)"

Tipos de Commit ​

TipoUsoVersion Bump
featureNueva funcionalidadMINOR
fixCorrección de bugPATCH
hotfixFix urgente en prodPATCH
refactorRefactorización—
docsDocumentación—
testTests—
choreMantenimiento/tooling—
perfPerformancePATCH
styleFormato de código—

Áreas por Repositorio ​

Backend (server/): ventas, compras, ctacte, tesoreria, contabilidad, stock, crm, config, auth, api, migrations

Frontend (public/): ventas, compras, ctacte, tesoreria, contabilidad, stock, crm, core, forms, hooks, frontend

Reportes (informes/): reportes, más módulos anteriores

Docs (docs/): docs (sin área en la mayoría de los casos)

Ejemplos Correctos ​

bash
feature/ctacte: agregar gestión de retenciones
fix/stock: corregir cálculo de inventario
hotfix/auth: resolver vulnerabilidad XSS
refactor/services: extraer lógica a Domain layer
test/ventas: agregar tests de integración
docs: actualizar README con configuración Docker
chore: actualizar dependencias de Composer
perf/reportes: optimizar consulta SQL de consolidación

Ejemplos Incorrectos ​

bash
❌ fix: correcciones               # sin área, vago
❌ Feature/ventas: Agregar algo.   # mayúscula, punto
❌ fix/ventas: fixed bug           # inglés, pasado
❌ feat(ventas): agregar algo      # formato incorrecto (paréntesis vs slash)
❌ feature/ventas+compras: cambios # múltiples áreas
❌ feature/ventas: agregar facturación con generación de XML completa  # >72 chars

# Footer PROHIBIDO:
❌ feature/ventas: agregar facturación
   Co-Authored-By: Claude <noreply@anthropic.com>

Cuándo Dividir Commits ​

Múltiples módulos:

bash
❌ feature/ventas+ctacte: agregar retenciones
✅ feature/ventas: agregar cálculo de retención en facturas
✅ feature/ctacte: registrar retenciones en cuenta corriente

Feature + tests:

bash
❌ feature/ventas: agregar facturación con tests
✅ feature/ventas: agregar facturación electrónica
✅ test/ventas: agregar tests de facturación

Fix + refactor:

bash
❌ fix/stock: corregir inventario y refactorizar
✅ fix/stock: corregir cálculo de inventario
✅ refactor/stock: simplificar lógica de cálculo

Checklist Pre-Commit ​

  • [ ] Formato: tipo/área: descripción | Sin footers | Máx 72 chars
  • [ ] Imperativo, minúsculas, sin punto | Atómico | Español
  • [ ] Área coincide con módulo afectado
  • [ ] git diff --staged revisado
  • [ ] Tests pasan

Checklist Pre-Merge (OBLIGATORIO) ​

Calidad de código ​

  • [ ] Dead code eliminado — sin imports, funciones o código comentado sin uso
  • [ ] Debug cleanup — sin console.log, var_dump, print_r, dd() en producción
  • [ ] Linters pasados — Backend: composer lint | Frontend: npx eslint .
  • [ ] Formatters aplicados — Backend: composer format | Frontend: npx prettier --check .

Git ​

  • [ ] Tests pasan | El código compila sin errores
  • [ ] Rebase sobre rama destino aplicado
  • [ ] Conflictos resueltos
  • [ ] Mensajes de commit siguien convención
  • [ ] CHANGELOG actualizado (si corresponde)
  • [ ] Versión bumpeada (si es release)
  • [ ] Working tree limpio (git status)
  • [ ] Diff revisado (git diff)

Versionado Semántico ​

Formato: MAJOR.MINOR.PATCH ​

3.10.5
│  │  └─ Bug fixes, hotfixes, performance (PATCH)
│  └──── Nueva funcionalidad compatible (MINOR)
└─────── Breaking changes (MAJOR)

Cuándo bumppear ​

Commit TypeBumpEjemplo
featureMINOR3.9.5 → 3.10.0
fixPATCH3.10.0 → 3.10.1
hotfixPATCH3.10.1 → 3.10.2
perfPATCH3.10.2 → 3.10.3
refactor—Sin bump
docs—Sin bump
test—Sin bump
chore—Sin bump
BreakingMAJOR3.10.5 → 4.0.0

Archivos a actualizar en release ​

  • server/composer.json → "version": "3.10.0"
  • server/config/app.php → 'version' => '3.10.0'
  • public/package.json → "version": "3.10.0"
  • CHANGELOG.md → agregar sección de versión

Tags ​

Formato ​

bash
# Git tag (lowercase v)
git tag -a v3.10.0 -m "Version 3.10.0"

# En CHANGELOG.md (Capital V)
## [V3.10.0] - 2026-02-24

Comandos ​

bash
# Crear tag anotado (RECOMENDADO)
git tag -a v3.10.0 -m "Version 3.10.0

Nuevas funcionalidades:
- Sistema de retenciones
Correcciones:
- Cálculo de IVA"

git push origin master --tags

# Listar tags
git tag -l | tail -5

# Ver detalles
git show v3.10.0

CHANGELOG.md ​

Todos los cambios deben reflejarse en CHANGELOG.md de cada repositorio.

Estructura ​

markdown
## [V3.10.0] - 2026-02-24

### Features
- Sistema integral de retenciones de ganancias
- Soporte para múltiples monedas en facturación

### Fixes
- Corrección de redondeo en módulo de ventas
- Error al guardar configuración de notificaciones

### Otros
- Actualización de dependencias internas

Regla: Capital V en los tags del CHANGELOG (V3.10.0), lowercase v en los tags de git (v3.10.0).

Comandos de Referencia ​

Gestión de ramas ​

bash
git branch -a                        # listar todas las ramas
git branch -d feature/mi-feature     # eliminar rama local
git push origin --delete feature/x   # eliminar rama remota
git switch branch-name               # cambiar de rama (moderno)

Rebase ​

bash
git rebase origin/develop     # rebase sobre develop
git rebase --abort            # abortar rebase
git rebase --continue         # continuar tras resolver conflictos

Stash ​

bash
git stash                          # guardar cambios temporalmente
git stash save "WIP: descripción"  # con mensaje
git stash list                     # listar stashes
git stash pop                      # recuperar último stash
git stash drop stash@{0}           # eliminar stash específico

Deshacer ​

bash
git reset --soft HEAD~1      # deshacer último commit (conserva cambios)
git reset --hard HEAD~1      # deshacer último commit (descarta cambios)
git revert <commit-hash>     # revertir commit (crea nuevo commit)
git restore --staged file    # destagear archivo

Historial ​

bash
git log --oneline --graph --all    # historial visual de ramas
git show <commit-hash>             # ver cambios de un commit
git log --grep="patrón"            # buscar por mensaje
git blame archivo.php              # ver autoría por línea

Recuperación de Emergencia ​

bash
# Encontrar commits perdidos
git reflog

# Restaurar commit perdido
git checkout <sha>
git checkout -b recovery-branch

# Recuperar rama eliminada
git reflog | grep branch-name
git checkout -b branch-name <sha>

Reglas Fundamentales ​

  1. Nunca commitear directamente a master
  2. Siempre pullear antes de crear ramas
  3. Commits atómicos — un cambio lógico por commit
  4. Rebase antes de mergear — evita conflictos en develop
  5. Squash merge para features — historial limpio en develop
  6. Tag en todos los releases — con versión semántica anotada
  7. CHANGELOG antes del release — Capital V en títulos