Versión: 1.0
Fecha: 23 de Enero, 2026
Estado: NORMATIVO - Ciclo de Vida de Desarrollo
Arquitecto: Carlos Alberto Torres Camargo
Nebula adopta el Modelo A: tres ramas permanentes (develop, qa, main) y tag SemVer al merge a main. No se usan release branches: la rama qa cumple el rol de hardening por ambiente.
| Rama | Tipo | Propósito | Deploy automático | Gate |
|---|---|---|---|---|
develop |
Permanente | Integración continua de features | nodo-01 DEV (auto) | Code review (Gatekeeper) |
qa |
Permanente | Hardening con equipo QA | nodo-02 QA (auto + input manual Jenkins) | QA Lead aprueba en Jenkins UI |
main |
Permanente | Producción | nodo-PROD (auto + input manual Jenkins) | Arquitecto aprueba; tag SemVer al merge |
Ramas efímeras:
feature/HT-CON-XXX-slug — desarrollo de nueva HT (deriva de develop).bugfix/HT-CON-XXX-fix-qa — corrección de defecto detectado en qa (deriva de qa).hotfix/vX.Y.Z-slug — emergencia en producción (deriva de main).Formato: <tipo>/<HT-id>-<descripcion-corta>
Ejemplos canónicos:
feature/HT-CON-019-crear-diferidos
feature/HT-CON-012-causacion-privado
bugfix/HT-CON-019-fix-qa
hotfix/v0.3.1-fix-calculo-iva
Reglas:
HT-CON-XXX que va en MAYÚSCULAS).HT-CON-019, no HT_CON_019).architecture/nebula-erp/htu/HT_CON_XXX_* (en el repo de arquitectura el folder usa _, en la branch usamos - por convención git).bugfix/ y sufijo -fix-qa. La rama deriva de qa, no de develop.# Actualizar develop
git checkout develop
git pull origin develop
# Crear feature branch
git checkout -b feature/NEB-156-integracion-dian
# Verificar
git branch
# Trabajar en el feature
# Hacer commits atómicos y descriptivos
# Commit siguiendo Conventional Commits
git add src/main/java/com/centrica/nebula/billing/service/DianService.java
git commit -m "feat(billing): implementar cliente DIAN para validación de facturas
- Crear DianWebClient con endpoints de validación
- Agregar DTOs DianRequest y DianResponse
- Implementar retry policy con Resilience4j
- Agregar tests unitarios con Mockito
Refs: NEB-156"
# Push al remoto (crear tracking)
git push -u origin feature/NEB-156-integracion-dian
# Opción A: Merge develop en feature (recomendado para features largos)
git checkout feature/NEB-156-integracion-dian
git merge develop
git push origin feature/NEB-156-integracion-dian
# Opción B: Rebase sobre develop (recomendado para features cortos y lineales)
git checkout feature/NEB-156-integracion-dian
git rebase develop
git push --force-with-lease origin feature/NEB-156-integracion-dian
Checklist antes de crear PR:
mvn test)mvn spotless:apply)developCrear PR:
# Title: [NEB-156] Integración con DIAN para validación de facturas
## Descripción
Implementa cliente HTTP para validar facturas electrónicas con DIAN antes de enviar al cliente.
## Cambios
- `DianWebClient`: Cliente reactivo con WebClient
- `DianService`: Lógica de validación con retry policy
- `FacturaService`: Integración con validación DIAN
- Tests: 95% cobertura en DianService
## Testing
- [x] Tests unitarios (Mockito)
- [x] Tests integración (Testcontainers con WireMock)
- [x] Pruebas manuales en DEV
## Checklist
- [x] Sin errores de compilación
- [x] Tests pasan
- [x] Código revisado por al menos 1 senior
- [x] Documentación actualizada
- [x] CHANGELOG.md actualizado
## Screenshots (si aplica)
[Adjuntar capturas de API response de DIAN]
Refs: #NEB-156
Revisores (mínimo 1):
Criterios de Aprobación:
Merge:
# Desde GitHub/GitLab UI:
# 1. Aprobar PR
# 2. Squash and Merge (para mantener historia limpia en develop)
# 3. Delete branch automáticamente
Modelo A: la rama
qareemplaza el concepto de release branch. La promoción es por merge directo entre ramas permanentes.
develop → qa (GATE-D)Quién la dispara: Backend Lead (autor) con firma del Arquitecto (revisor), al cierre de sprint o cuando hay un lote estable de HT mergeadas en develop. Esta promoción corresponde al GATE-D del flujo de entrega formalizado en ADR-003 Política Entrega QA.
Pre-requisitos (DoD-QA completo):
Lista resumida. Referencia completa en DEFINITION_OF_DONE §3.
develop con DoD-DEV verde.develop está estable (sin builds rojos pendientes).architecture/sprint-N/QA_HANDOFF.md instanciado desde QA_HANDOFF_TEMPLATE.md y firmado por Backend Lead.architecture/sprint-N/postman/ con collection completa para el lote.architecture/sprint-N/data-fixtures/ con SQL seed si las HT lo requieren.[Unreleased] con las HT del lote.develop-<sha>-<build#> publicada en registry; tag candidato SemVer decidido.QA_HANDOFF.md mismo día hábil — SLA en POLITICA_REGRESION_QA §4).Procedimiento:
# Sincronizar
git checkout develop
git pull origin develop
git checkout qa
git pull origin qa
# Merge no-fast-forward para conservar trazabilidad del corte
git merge --no-ff develop -m "chore(qa): promover develop a qa para sprint-N
HTs incluidas: HT-CON-012, HT-CON-019
Tag candidato: v0.3.0
QA_HANDOFF: architecture/sprint-3/QA_HANDOFF.md"
git push origin qa
El push dispara webhook → Jenkins → build → input manual del QA Lead → deploy a nodo-02.
Regla: los fixes de QA se aplican primero a
qa, luego se sincronizan adevelop. Esto aísla el lote bajo prueba de nuevas features que ya están endeveloppara el siguiente sprint.
# 1. Fix branch desde qa (NO desde develop)
git checkout qa
git pull origin qa
git checkout -b bugfix/HT-CON-019-fix-qa
# 2. Corregir, commit, push
git commit -m "fix(accounting): corregir cálculo de cuota en diferidos
Defecto detectado en QA build v0.3.0-rc.
Refs: HT-CON-019"
git push -u origin bugfix/HT-CON-019-fix-qa
# 3. MR a qa (revisado por Gatekeeper, fast-track)
# Una vez mergeado, Jenkins redeploy a nodo-02
# 4. Sincronizar fix a develop (CRÍTICO — no olvidar)
git checkout develop
git pull origin develop
git merge --no-ff qa -m "chore(sync): traer fixes de qa a develop"
git push origin develop
# 5. Eliminar bugfix branch
git push origin --delete bugfix/HT-CON-019-fix-qa
Por qué qa → develop y no al revés: durante el hardening del lote, develop puede tener HT del siguiente sprint ya mergeadas. Mergear develop → qa arrastraría esas HT al ambiente bajo prueba. Por eso el fix entra a qa y baja a develop.
qa → main (Release a Producción)Quién la dispara: Arquitecto, cuando QA ha aprobado el lote completo en Jenkins UI.
Pre-requisitos:
QA_HANDOFF.md marcados como aprobados.[Unreleased] → [vX.Y.Z] con fecha.pom.xml con versión sin -SNAPSHOT.Procedimiento:
# Versionado y CHANGELOG en qa antes del merge
git checkout qa
git pull origin qa
# Editar pom.xml: 0.3.0-SNAPSHOT → 0.3.0
# Editar CHANGELOG.md: [Unreleased] → [0.3.0] - 2026-05-14
git add pom.xml CHANGELOG.md
git commit -m "chore(release): bump version to 0.3.0"
git push origin qa
# Merge a main
git checkout main
git pull origin main
git merge --no-ff qa -m "release: v0.3.0"
git push origin main
# Tag SemVer
git tag -a v0.3.0 -m "Release v0.3.0: Sprint-3 (HT-CON-012, HT-CON-019)"
git push origin v0.3.0
# Sync a develop (incluye bump de versión)
git checkout develop
git pull origin develop
git merge --no-ff main -m "chore(sync): traer release v0.3.0 a develop"
# Reabrir versión SNAPSHOT en develop
# Editar pom.xml: 0.3.0 → 0.4.0-SNAPSHOT
git add pom.xml
git commit -m "chore: open 0.4.0-SNAPSHOT"
git push origin develop
El push a main dispara webhook → Jenkins → build → input manual del Arquitecto → deploy a nodo-PROD.
## [0.3.0] - 2026-05-14
### Added
- HT-CON-012: Causación cuentas modelo privado (26 endpoints)
- HT-CON-019: Crear diferidos con orquestador transaccional
### Fixed
- HT-CON-019: cálculo de cuota corregido (defecto QA build v0.3.0-rc1)
# Desde main (producción está rota!)
git checkout main
git pull origin main
# Crear hotfix con nueva versión PATCH
git checkout -b hotfix/v1.3.1-fix-calculo-impuestos
# Fix del bug
git add src/main/java/com/centrica/nebula/billing/service/TaxCalculationService.java
git commit -m "fix(billing): corregir cálculo de IVA en productos exentos
El cálculo de IVA aplicaba 19% incluso a productos con exención.
Agregado condicional para validar exención antes de calcular.
BREAKING: None
IMPACTO: Facturas emitidas entre 2025-01-10 y 2025-01-15 pueden tener IVA incorrecto
Refs: HOTFIX-001"
git push -u origin hotfix/v1.3.1-fix-calculo-impuestos
# Test rápido pero exhaustivo
mvn clean verify
# PR a main (fast-track, sin esperar a CI completo)
# Aprobar con 1 senior + comunicar a equipo
# Merge a main
git checkout main
git pull origin main
git merge --no-ff hotfix/v1.3.1-fix-calculo-impuestos
# Tag
git tag -a v1.3.1 -m "Hotfix v1.3.1: Corregir cálculo de IVA en exentos"
git push origin main --tags
# Merge a qa (puede estar en hardening de un lote — el fix debe estar ahí también)
git checkout qa
git pull origin qa
git merge --no-ff main -m "chore(sync): traer hotfix v1.3.1 a qa"
git push origin qa
# Merge a develop (para que no se pierda el fix)
git checkout develop
git pull origin develop
git merge --no-ff main -m "chore(sync): traer hotfix v1.3.1 a develop"
git push origin develop
# Eliminar hotfix branch
git push origin --delete hotfix/v1.3.1-fix-calculo-impuestos
Sync obligatorio en Modelo A: un hotfix se sincroniza a
main → qa → develop. Si se omite el sync aqa, la próxima promocióndevelop → qapuede sobreescribir o conflictar con el hotfix. Si se omite adevelop, el bug reaparece en el siguiente sprint.
<tipo>(scope): <descripción corta>
<cuerpo opcional: explicación detallada>
<footer opcional: referencias, breaking changes>
| Tipo | Descripción | Incremento SemVer |
|---|---|---|
feat |
Nueva funcionalidad | MINOR (1.X.0) |
fix |
Corrección de bug | PATCH (1.0.X) |
docs |
Solo documentación | - |
style |
Formato, sin cambios de lógica | - |
refactor |
Refactorización sin cambiar comportamiento | - |
perf |
Mejora de performance | PATCH |
test |
Agregar o corregir tests | - |
chore |
Cambios de build, deps, CI | - |
build |
Cambios en build system (Maven, npm) | - |
ci |
Cambios en CI/CD | - |
revert |
Revertir commit previo | depende |
Backend:
accounting (módulo de contabilidad)billing (facturación)inventory (inventarios)payroll (nómina)core (shared/commons)config (configuración)security (autenticación/autorización)Frontend:
ui (componentes visuales)forms (formularios)routing (navegación)state (gestión de estado)services (servicios HTTP)Ejemplo: 2.5.3
MAJOR (1.0.0 → 2.0.0):
MINOR (1.2.0 → 1.3.0):
PATCH (1.2.3 → 1.2.4):
Documento Técnico - GitFlow Detallado
© 2025 CatcSoft - Medellín, Colombia
| Version | Fecha | Autor | Descripcion |
|---|---|---|---|
| 2.0.0 | 2026-05-07 | Carlos Torres | Adopcion de Modelo A (rama qa permanente) en lugar de release branches. Convencion de naming HT-CON-XXX. Mitigacion de fixes detectados en QA via bugfix/*-fix-qa con sync qa->develop. Alineado con CICD_HOJA_RUTA_QA_PROD.md y FLUJO_HT_A_PROD.md. |
| 1.1.0 | 2026-03-04 | Carlos Torres | Revision, sanitizacion y publicacion en Wiki Arquitectura Centrica. |
| 1.0.0 | 2025-12-27 | Carlos Torres | Creacion del documento. |