Versión: 1.1.0
Fecha: 2026-05-11
Estado: NORMATIVO — Ciclo de Vida de una HT
Arquitecto: Carlos Alberto Torres Camargo
Documento maestro de la política de entrega: ADR-003 Política Entrega QA. Las Fases descritas en este documento corresponden a los gates A–G definidos allí.
Este documento describe el ciclo de vida completo de una Historia Técnica (HT) en Nebula, desde su definición arquitectónica hasta el tag de release en producción. Cose lo que ya está definido en otros documentos:
STD-015, PROMPT_VALIDACION_HU.md, SPRINT_CREATION_PROCESS.md.FLUJO_DESARROLLO_NEBULA.md, GUIA_CREAR_FEATURE_BACKEND.md.GITFLOW_DETALLADO.md.CICD_HOJA_RUTA_QA_PROD.md, PIPELINE_CICD.md.PROCESO_OPERATIVO_FABRICA_SOFTWARE.md, ROLES_RESPONSABILIDADES_FABRICA.md.DEFINITION_OF_DONE.md.POLITICA_REGRESION_QA.md.POLITICA_ROLLBACK.md.QA_HANDOFF_TEMPLATE.md, QA_EXECUTION_REPORT_TEMPLATE.md, QA_CLOSURE_TEMPLATE.md.Pilotaje: nebula-accounting-core (sprint-3).
feature/HT-CON-XXX-slug ──► develop ──► qa ──► main
│ │ │
nodo-01 DEV nodo-02 QA nodo-PROD
(gate QA) (gate Arq)
│
└─► tag vX.Y.Z
Tres ramas permanentes (develop, qa, main) + ramas efímeras (feature/*, bugfix/*-fix-qa, hotfix/*). Sin release branches: la rama qa cumple ese rol.
Detalle completo: GITFLOW_DETALLADO.md §1.
Quién: Arquitecto.
Repo: architecture (rama main del repo de arquitectura).
Entrada: Historia de Usuario en architecture/nebula-erp/hu/HU_CON_XXX_*/.
Salida: Folder architecture/nebula-erp/htu/HT_CON_XXX_*/ con plantilla canónica:
HT_CON_019_CrearDiferidos/
├── README.md
├── 01_Model.md
├── 02_Data.md
├── 03_Rules.md
├── 04_References.md
├── 05_Checklist.md
├── 06_Delivery.md
├── 07_TestCases.md
├── 08_Contracts.md
└── 09_Simulator.md
Reglas:
STD-015 (paginación dual, multi-tenant, i18n, naming, etc.).07_TestCases.md es la base sobre la que QA construye su plan de pruebas.08_Contracts.md define el contrato OpenAPI que Frontend y QA consumen.Quién: Arquitecto + Backend Lead.
Repo: architecture/sprint-N/.
Salida:
PLAN_SPRINT_NN_BACKEND_*.md con HT priorizadas, cronograma diario, dependencias.htu/ y hu/ simbólicos o copiados con las HT del sprint.FRONTEND_HANDOFF.md (firmado al cierre del sprint).QA_HANDOFF.md — nuevo entregable del Modelo A (ver §3 más abajo).Quién: Backend Sr/Jr.
Repo: servicio (ej. nebula-accounting-core).
Pasos:
Crear branch desde develop:
git checkout develop
git pull origin develop
git checkout -b feature/HT-CON-019-crear-diferidos
Naming: feature/HT-CON-XXX-slug-corto (guion en el ID, mayúsculas, slug en minúsculas, máximo 50 caracteres).
Implementar siguiendo STD-015 y los archivos 01-09 de la HT.
Tests unitarios + integración (cobertura >80%).
Commit con Conventional Commits referenciando la HT:
feat(accounting): orquestador transaccional de diferidos
- DiferidoComponent.crearDesdeCausacion()
- Cuotas + distribución CC en una sola transacción
- Tests JUnit 5 + Testcontainers Oracle XE
Refs: HT-CON-019
MR a develop. Reviewer obligatorio: Gatekeeper.
Salida: MR mergeado a develop. Pipeline DEV despliega automáticamente a nodo-01.
Estado HT: Implementada (en develop, no aceptada todavía).
Quién: Gatekeeper, manualmente, al cierre de sprint o cuando hay un lote estable.
Frecuencia: una promoción por sprint (típico) o por lote estable.
Pre-requisitos:
develop.architecture/sprint-N/QA_HANDOFF.md está completo.[Unreleased] con las HT del lote.Acción: MR develop → qa (no fast-forward). Procedimiento exacto en GITFLOW_DETALLADO.md §3.1.
Salida: push a qa dispara webhook → Jenkins → build → input manual del QA Lead → deploy a nodo-02.
Estado HT: En QA.
Quién: equipo QA.
Ambiente: nodo-02 (http://<nodo-02>:<port>/swagger-ui.html y endpoints según 08_Contracts.md).
Insumo: QA_HANDOFF.md (ver plantilla en §3).
Outcomes posibles:
Aceptada. El lote queda listo para promoción a main.bugfix/HT-CON-XXX-fix-qa desde qa. Procedimiento en GITFLOW_DETALLADO.md §3.2 y CICD_HOJA_RUTA_QA_PROD.md §5.1. Crítico: sincronizar qa → develop después de mergear el fix.Estado HT: Aceptada cuando todos los casos de 07_TestCases.md pasan en nodo-02.
Quién: Arquitecto.
Pre-requisitos:
QA_HANDOFF.md con todos los casos aprobados.GITFLOW_DETALLADO.md §6).[vX.Y.Z] y fecha.pom.xml con versión sin -SNAPSHOT.Acción: MR qa → main + tag SemVer. Procedimiento en GITFLOW_DETALLADO.md §3.3.
Salida: push a main → Jenkins → build → input manual del Arquitecto → deploy a nodo-PROD. Tag vX.Y.Z publicado.
Estado HT: Released vX.Y.Z.
Quién: Arquitecto.
Acción:
En architecture/nebula-erp/htu/HT_CON_XXX_*/README.md, actualizar el bloque de estado:
## Estado
- Implementada: 2026-05-04 (sprint-3, develop)
- Aceptada: 2026-05-12 (sprint-3, qa)
- Released: 2026-05-14 (v0.3.0)
Commit en architecture referenciando el tag.
Cerrar el ticket en JIRA/GitLab.
No se versiona por sprint. Cada lote qa → main produce un tag independiente del sprint que lo originó.
Cómo se decide la versión:
| Tipo de cambios en el lote | Incremento |
|---|---|
Solo fix: y chore: |
PATCH (0.3.0 → 0.3.1) |
Al menos un feat: sin breaking changes |
MINOR (0.3.0 → 0.4.0) |
Al menos un commit con BREAKING CHANGE: en footer |
MAJOR (0.3.0 → 1.0.0) |
Mientras el producto esté en pre-release (versión 0.x.y), MAJOR se reserva para hitos del producto, no por commits aislados.
| Estado | Dónde queda registrado | Quién lo marca |
|---|---|---|
Definida |
htu/HT_CON_XXX_*/README.md creado |
Arquitecto |
En desarrollo |
branch feature/HT-CON-XXX-slug abierta |
Backend Sr/Jr |
Implementada |
MR mergeado a develop |
Gatekeeper |
En QA |
merge develop → qa deployado a nodo-02 |
Gatekeeper |
Aceptada |
QA aprueba en Jenkins UI | QA Lead |
Released vX.Y.Z |
tag publicado en main |
Arquitecto |
Bloqueada |
issue/MR con label blocked |
cualquiera |
Rechazada |
issue cerrado con label rejected |
Arquitecto |
| Fase | Arquitecto | Gatekeeper | Backend Sr | QA Lead | DevOps |
|---|---|---|---|---|---|
| 1. Definición HT | R/A | C | C | C | I |
| 2. Plan sprint | R/A | C | C | C | I |
| 3. Implementación | I | C | R/A | I | I |
| 4. Promoción a QA | I | R/A | C | C | I |
| 5. Pruebas QA | I | C | C | R/A | I |
| 6. Release a PROD | R/A | C | I | C | C |
| 7. Cierre HT | R/A | I | I | I | I |
Detalle completo del RACI en PROCESO_OPERATIVO_FABRICA_SOFTWARE.md §2.1.
QA_HANDOFF.mdPlantilla canónica del entregable de Fase 4: architecture/nebula-erp/QA_HANDOFF_TEMPLATE.md.
Una instancia por sprint en architecture/sprint-N/QA_HANDOFF.md.
| Version | Fecha | Autor | Descripcion |
|---|---|---|---|
| 1.0.0 | 2026-05-07 | Carlos Torres | Creacion del documento end-to-end alineando GITFLOW_DETALLADO v2.0.0 + CICD_HOJA_RUTA_QA_PROD v1.2.0. Modelo A confirmado. |