diff --git a/docs/gobernanza/qa/QA-ANALISIS-RAMAS-001/QA-ANALISIS-RAMAS-001.md b/docs/gobernanza/qa/QA-ANALISIS-RAMAS-001/QA-ANALISIS-RAMAS-001.md new file mode 100644 index 00000000..3fa9296f --- /dev/null +++ b/docs/gobernanza/qa/QA-ANALISIS-RAMAS-001/QA-ANALISIS-RAMAS-001.md @@ -0,0 +1,73 @@ +--- +id: QA-ANALISIS-RAMAS-001 +estado: borrador +propietario: lider-qa +ultima_actualizacion: 2024-06-01 +version: 1.0 +relacionados: + - docs/standards/engineering-ruleset.md + - docs/gobernanza/qa/QA-ANALISIS-ESTRUCTURA-003 +--- +# QA-ANALISIS-RAMAS-001 + +## 1. Portada + +- **Versión:** 1.0 +- **Fecha:** 2024-06-01 +- **Sistema/equipo:** Gestión de ramas y releases + +## 2. Objetivo + +Asegurar que la estrategia de ramas cumpla con las reglas de gobernanza, reduce riesgos de integraciones defectuosas y garantiza trazabilidad entre cambios, revisiones y despliegues. + +## 3. Alcance + +- **Incluye:** ramas permanentes (`main`, `develop`), ramas de soporte (hotfix, release) y ramas efímeras de feature/experimentales. +- **Excluye:** configuraciones de CI/CD no relacionadas con políticas de ramas y controles específicos de seguridad estática. + +## 4. Responsables + +| Rol | Responsabilidad | Contacto / canal | +| --- | --- | --- | +| Liderazgo QA | Aprobar cambios al flujo de ramas y sus métricas de calidad | #qa-gobernanza | +| Dev Lead | Implementar políticas y proteger ramas en el repositorio | #engineering | +| Release Manager | Validar cumplimiento antes de cortes y etiquetado | #releases | + +## 5. Frecuencia + +- Revisión completa por release o cambio mayor de flujo. +- Verificación parcial semanal sobre ramas activas. + +## 6. Checklist operativo + +| Paso | Acción | Evidencia esperada | Estado | +| --- | --- | --- | --- | +| Definir convenciones de nombres | Ramas con prefijos `feature/`, `hotfix/`, `release/`, `experiment/` | Listado exportado desde el repositorio | +| Protección de ramas principales | `main` y `develop` con políticas de revisión requerida y status checks obligatorios | Capturas de configuración o policy-as-code | +| Reglas de merge | Uso de squash/rebase según política y restricción de `force push` | Registro de auditoría del repositorio | +| Trazabilidad | Asociación de PRs a issues o tickets vinculados | Reporte de enlaces o etiquetas | +| Housekeeping | Eliminación automática de ramas mergeadas y expiración de ramas huérfanas | Evidencia de políticas o jobs programados | + +## 7. Métricas + +| Métrica | Definición | Umbral | Fuente | +| --- | --- | --- | --- | +| Ratio de PRs aprobados sin excepciones | PRs aprobados con todos los checks vs. total de PRs mergeados | ≥ 95% | Datos del repositorio / API | +| Tiempo medio de ciclo de rama | Tiempo desde creación hasta merge | ≤ 14 días | API de repositorio | +| Ramas huérfanas | Número de ramas sin actividad > 30 días | 0 | Auditoría semanal | + +## 8. Convenciones de nomenclatura + +- Aplicar prefijos según tipo de trabajo (`feature/`, `hotfix/`, `release/`, `experiment/`). +- Mantener `kebab-case` en el resto del nombre (`feature/refactor-cache-layer`). +- Seguir las reglas de `Naming Conventions` en `docs/standards/engineering-ruleset.md` para coherencia transversal. + +## 9. Registro de decisiones y observaciones + +- Documentar excepciones aprobadas y la justificación de riesgo asumido. +- Registrar acciones correctivas cuando un control falle (p. ej., release revertido). + +## 10. Trazabilidad y anexos + +- Enlazar al pipeline o políticas de protección de ramas vigentes. +- Referenciar tableros o reportes de seguimiento si aplican. diff --git a/docs/gobernanza/qa/README.md b/docs/gobernanza/qa/README.md index 3506fce2..1ec5fe97 100644 --- a/docs/gobernanza/qa/README.md +++ b/docs/gobernanza/qa/README.md @@ -16,6 +16,7 @@ Centraliza la estrategia, métricas y evidencias de aseguramiento de calidad par - [`estrategia_qa.md`](estrategia_qa.md) - [`actividades_garantia_documental.md`](actividades_garantia_documental.md) - [`registros/`](registros/) +- [`guia_estructura_qa.md`](guia_estructura_qa.md) ## Información clave ### Rol dentro del flujo de documentación diff --git a/docs/gobernanza/qa/guia_estructura_qa.md b/docs/gobernanza/qa/guia_estructura_qa.md new file mode 100644 index 00000000..a0b29595 --- /dev/null +++ b/docs/gobernanza/qa/guia_estructura_qa.md @@ -0,0 +1,144 @@ +--- +id: DOC-QA-GUIA-ESTRUCTURA +estado: borrador +propietario: lider-qa +ultima_actualizacion: 2025-02-25 +relacionados: ["CHECK-AUDIT-REST", "DOC-QA-001"] +--- +# Guía rápida para nuevas guías de QA + +Esta guía toma como referencia `checklist_auditoria_restricciones.md` para documentar la estructura mínima y las convenciones de nomenclatura que deben cumplir las futuras guías de QA. + +## Mapeo del archivo de referencia +- **Metadatos YAML**: `id`, `tipo`, `categoria`, `version`, `fecha_creacion`, `propietario`, `relacionados`. +- **Encabezados principales** (en mayúsculas): Propósito, CÓMO USAR ESTE CHECKLIST, SECCIÓN 1 (restricciones críticas) con subsecciones numeradas, SECCIÓN 2 y SECCIÓN 3, RECURSOS Y REFERENCIAS, HISTORIAL DE AUDITORÍAS, FIRMA DE APROBACIÓN. +- **Secciones clave**: + - Objetivo: se expone en “Propósito”. + - Alcance: descrito en la sección de uso y en los bloques de restricciones (alcances CRÍTICO/ALTA/MEDIA/BAJA). + - Checklist: tablas numeradas por categoría (1.x, 2.x, 3.x) con columnas `#`, `Ítem`, `Verificación`, `Estado`, `Evidencia` y sumarios de puntaje. + - Métricas: scoring mínimo y puntajes por sección (Score 1.x, Score 2.x, Score 3.x). + - Responsables: roles explícitos en la firma de aprobación (QA Lead, Security Lead, Tech Lead). + - Frecuencia: subsección “Frecuencia de Auditoría” dentro de CÓMO USAR ESTE CHECKLIST. +- **Tablas**: usadas para checklist por sección, métricas de seguridad, recursos de archivos y firmas. Todas usan encabezados en mayúsculas y numeración alineada con el bloque (1.1, 1.2...). +- **Nomenclatura**: IDs en mayúsculas con prefijos (ej. `CHECK-AUDIT-REST`), versiones semánticas, subtítulos numerados (`### 1.1 Comunicaciones [CRÍTICO]`), listas de acciones pendientes con casillas `[ ]`. + +## Elementos obligatorios para nuevas guías de QA +1. **Metadatos YAML** con `id`, `estado`, `propietario`, `ultima_actualizacion`, `relacionados` y, si aplica, `tipo`, `categoria`, `version`, `fecha_creacion`. +2. **Objetivo y alcance**: subsección corta que aclare propósito y límites del documento. +3. **Frecuencia y responsables**: bloque dedicado a cuándo se ejecuta la guía y quién la aprueba (roles mínimos: QA Lead; agregar Security/Tech Lead cuando proceda). +4. **Checklist estructurado**: + - Numeración jerárquica por categoría (`1.x`, `2.x`, etc.). + - Tablas con columnas `#`, `Ítem`, `Verificación`, `Estado`, `Evidencia`. + - Cierre de cada subsección con puntaje o métricas de cumplimiento. +5. **Métricas y criterios de aceptación**: metas mínimas (ej. puntuación global, cobertura ≥ 80 %) y umbrales por severidad. +6. **Acciones pendientes**: lista de tareas o remediaciones con casillas `[ ]` vinculadas a cada sección. +7. **Recursos y referencias**: enlaces a documentos relacionados y herramientas sugeridas. +8. **Historial y firma**: tabla de auditorías previas y bloque de firmas para responsables. +9. **Nomenclatura**: mantener IDs en mayúsculas con prefijos descriptivos (`CHECK-`, `DOC-`, `PLAN-`), subtítulos numerados y uso consistente de mayúsculas en encabezados principales. + +## Plantilla mínima sugerida +```markdown +--- +id: CHECK-NNN +estado: borrador +propietario: rol-responsable +ultima_actualizacion: AAAA-MM-DD +relacionados: ["..."] +--- +# Título de la guía + +## Propósito y alcance +- Objetivo +- Alcance + +## Frecuencia y responsables +- Frecuencia +- Roles: QA Lead / Security Lead / Tech Lead + +## Checklist +### 1.1 Tema [CRÍTICO] +| # | Ítem | Verificación | Estado | Evidencia | +|---|------|--------------|--------|-----------| +| 1.1.1 | ... | ... | ... | ... | + +**Score 1.1**: X/X - Estado + +## Métricas y criterios +- Puntuación mínima global +- Criterios por severidad + +## Acciones pendientes +- [ ] Acción + +## Recursos y referencias +- ... + +## Historial de auditorías +| Fecha | Auditor | Score Global | Estado | Notas | +| --- | --- | --- | --- | --- | + +## Firma de aprobación +- QA Lead: ___ Fecha: ___ +- Security Lead: ___ Fecha: ___ +- Tech Lead: ___ Fecha: ___ +``` + +## Guía de QA: mapeo de referencia y estilo + +### 1. Archivo de referencia identificado + +- **Ruta:** `docs/standards/engineering-ruleset.md`. +- **Propósito del archivo:** consolidar convenciones técnicas y de nomenclatura para el monorrepo (equivalente a un objetivo). +- **Alcance explícito:** cubre estándares de repositorio, Bash, Python, UI y automatización; aplica a todo `docs/` y a las capas descritas (presentación, dominio, infraestructura). + +### 2. Mapa de estructura del archivo de referencia + +| Orden | Encabezado / sección | Contenido clave | Elementos relevantes para QA | +| --- | --- | --- | --- | +| 1 | Título y resumen inicial | Presenta el propósito del ruleset y su carácter viviente. | Objetivo y alcance implícitos. | +| 2 | `1. Core Principles` | Lista numerada con principios base. | Actúa como checklist de lineamientos generales. | +| 3 | `2. Repository Structure Expectations` | Diagrama de árbol del monorrepo con comentarios. | Define alcance y dependencias. | +| 4 | `3. Naming Conventions` | Tabla con convenciones por capa (Bash, Python, React, SCSS, Webpack, PlantUML). | Convenciones de nomenclatura obligatorias. | +| 5 | `4. Layering Rules` | Lista numerada con límites de responsabilidad. | Checklist de responsabilidades y restricciones. | +| 6 | `5. Bash Standards` | Bullets de prácticas obligatorias. | Lista de verificación para scripts. | +| 7 | `6. Python (Flask + PyTM) Standards` | Bullets de estilo y organización. | Lista de verificación por lenguaje. | +| 8 | `7. PlantUML and Diagram Automation` | Bullets sobre ubicación y generación de diagramas. | Checklist especializado. | +| … | Secciones posteriores | Continúan con estándares por capa (no visibles en este extracto). | Extienden checklists y reglas específicas. | + +#### Convenciones de nomenclatura derivadas + +- Usar `snake_case` para scripts Bash y módulos/funciones Python. +- Emplear `PascalCase` para clases Python y componentes React. +- Archivos SCSS en `kebab-case`, variables en `$kebab-case`. +- Configuraciones de Webpack como `webpack..config.js`. +- Plantillas PlantUML en `snake_case.puml`. + +### 3. Guía de estilo para nuevas guías de QA + +Al crear futuras guías de QA en este repositorio, incluye como mínimo: + +1. **Portada breve:** título, versión, fecha y sistema o equipo al que aplica. +2. **Objetivo:** párrafo que explique qué se valida o protege. +3. **Alcance:** listado con límites (incluye/excluye). Si aplica a un módulo específico, referéncialo. +4. **Responsables:** tabla con rol, responsabilidad y contacto/canal. +5. **Frecuencia:** periodicidad de ejecución (por ciclo, semanal, por release) y disparadores. +6. **Checklist operativo:** tabla `| Paso | Acción | Evidencia esperada | Estado |` para asegurar trazabilidad. +7. **Métricas:** tabla mínima `| Métrica | Definición | Umbral | Fuente |`. +8. **Convenciones de nomenclatura:** referencias a la tabla del archivo de referencia y reglas específicas de QA (p. ej., prefijos para casos de prueba). +9. **Registro de decisiones/observaciones:** bullets con hallazgos, desvíos y acciones correctivas. +10. **Trazabilidad y anexos:** enlaces relativos a scripts, pipelines o plantillas utilizadas. + +#### Reglas de formato + +- Mantén encabezados numerados para reflejar orden y facilitar auditorías. +- Usa tablas para checklist, métricas y responsables; alinea columnas con `|` para lecturabilidad. +- Coloca código o comandos en bloques de triple acento invertido con idioma cuando aplique. +- Nombra archivos de QA en `kebab-case` (`control-versionado-qa.md`) y rutas bajo `docs/gobernanza/qa/`. +- Si introduces nuevas convenciones, documenta el objetivo y enlaza al recurso correspondiente dentro del repositorio. + +### 4. Ubicación y nomenclatura confirmada + +- No existen variantes previas (`.md`, `.adoc`, `.pdf`) de las guías solicitadas bajo `docs/` o `infrastructure/`. +- Se crean y consolidan las rutas acordadas para QA: + - `docs/gobernanza/qa/QA-ANALISIS-RAMAS-001/QA-ANALISIS-RAMAS-001.md` para el control de ramas. + - `docs/infraestructura/qa/QA-ANALISIS-ESTRUCTURA-INFRA-001/QA-ANALISIS-ESTRUCTURA-INFRA-001.md` para la estructura de infraestructura. diff --git a/docs/infraestructura/qa/QA-ANALISIS-ESTRUCTURA-INFRA-001/INDICE.md b/docs/infraestructura/qa/QA-ANALISIS-ESTRUCTURA-INFRA-001/INDICE.md index 36cd7414..430a33b8 100644 --- a/docs/infraestructura/qa/QA-ANALISIS-ESTRUCTURA-INFRA-001/INDICE.md +++ b/docs/infraestructura/qa/QA-ANALISIS-ESTRUCTURA-INFRA-001/INDICE.md @@ -70,6 +70,15 @@ Dos analisis complementarios que trabajan en conjunto: **Documentos principales:** +#### Vista rapida de documentos clave +| Archivo | Tipo | Proposito | Hallazgos o entregables clave | +| --- | --- | --- | --- | +| `ANALISIS-ESTRUCTURA-INFRA-2025-11-18.md` | Analisis tecnico | Inventario de estructura, brechas contra Gobernanza y plan de accion inmediato. | 32 README/INDEX inventariados, brechas en QA/testing/registros y plantillas QA creadas como primeras acciones. | +| `PLAN-DOCUMENTACION-INFRA-2025-11-19.md` | Plan de accion | Roadmap de tareas (Fases Descubrimiento → Gobernanza) para igualar la madurez de QA respecto a Gobernanza. | 8 tareas con dependencias y restricciones obligatorias (TDD, cobertura >=80%, commits convencionales). | +| `README-REORGANIZACION-ESTRUCTURA.md` | Analisis de reorganizacion | Propuesta top-down de estructura objetivo y gaps cuantificados (carpetas, ADR, procesos, plantillas). | 13 carpetas nuevas requeridas, 65 tareas estimadas en 6 semanas con metricas de exito y riesgos. | +| `LISTADO-COMPLETO-TAREAS.md` | Backlog | Inventario consolidado de tareas P0–P4 y dependencias cruzadas entre analisis y ejecucion. | Trazabilidad hacia `tareas_activas.md` y tareas numeradas TASK-001 a TASK-040. | +| `MATRIZ_HALLAZGOS_INFRAESTRUCTURA.csv` | Matriz de hallazgos | Evidencias y severidad por hallazgo con responsables sugeridos. | Alimenta las tareas P1–P3 de correccion y los checks de QA semanal. | + #### 1.1. ANALISIS-ESTRUCTURA-INFRA-2025-11-18.md **Tipo:** Analisis Tecnico **Proposito:** Analisis inicial de estructura y plan de accion para documentar componentes @@ -412,6 +421,14 @@ Al finalizar ambos analisis, se obtiene: - `docs/gobernanza/qa/QA-ANALISIS-RAMAS-001/` - Modelo de analisis QA - `docs/gobernanza/qa/ANALISIS-GOBERNANZA-POST-LIMPIEZA-2025-11-17.md` - Analisis de duplicados (complementario) +#### Integracion con gobernanza/qa + +| Documento | Proposito | Como usarlo en este analisis | +| --- | --- | --- | +| `docs/gobernanza/qa/README.md` | Portada QA con metadatos y artefactos obligatorios (estrategia, controles documentales, registros). | Alinear el frontmatter y las secciones de cumplimiento de este indice con el formato corporativo y replicar las acciones prioritarias (cobertura >= 80 %, criterios de salida APScheduler). | +| `docs/gobernanza/qa/guia_estructura_qa.md` | Guía rápida de estructura y nomenclatura para nuevas guías QA basada en `checklist_auditoria_restricciones.md`. | Usar la plantilla para crear futuros checklists de infraestructura (IDs en mayúsculas, tablas 1.x, columnas `#`, `Ítem`, `Verificación`, `Estado`, `Evidencia`, bloque de métricas y firmas). | +| `docs/gobernanza/qa/checklist_auditoria_restricciones.md` | Checklist de referencia con secciones numeradas y scoring por bloque. | Tomar como referencia para construir checklists específicos de infraestructura (por ejemplo, hardening de VMs o DevContainers) respetando numeración y encabezados en mayúsculas. | + **En docs/backend/:** - `docs/backend/qa/QA-ANALISIS-ESTRUCTURA-BACKEND-001/` - Modelo de reorganizacion de otro dominio diff --git a/docs/infraestructura/qa/QA-ANALISIS-ESTRUCTURA-INFRA-001/QA-ANALISIS-ESTRUCTURA-INFRA-001.md b/docs/infraestructura/qa/QA-ANALISIS-ESTRUCTURA-INFRA-001/QA-ANALISIS-ESTRUCTURA-INFRA-001.md new file mode 100644 index 00000000..5522a137 --- /dev/null +++ b/docs/infraestructura/qa/QA-ANALISIS-ESTRUCTURA-INFRA-001/QA-ANALISIS-ESTRUCTURA-INFRA-001.md @@ -0,0 +1,76 @@ +--- +id: QA-ANALISIS-ESTRUCTURA-INFRA-001 +estado: borrador +propietario: lider-qa +ultima_actualizacion: 2024-06-01 +version: 1.0 +relacionados: + - docs/standards/engineering-ruleset.md + - docs/gobernanza/qa/QA-ANALISIS-RAMAS-001 +--- +# QA-ANALISIS-ESTRUCTURA-INFRA-001 + +## 1. Portada + +- **Versión:** 1.0 +- **Fecha:** 2024-06-01 +- **Sistema/equipo:** Infraestructura de ejecución y despliegue + +## 2. Objetivo + +Validar que la estructura de infraestructura (carpetas, scripts, configuraciones y artefactos de despliegue) cumpla con estándares de seguridad, observabilidad y mantenibilidad definidos para el monorrepo, con el mismo nivel de trazabilidad que el control de ramas. + +## 3. Alcance + +- **Incluye:** organización de `infrastructure/`, scripts de automatización, configuraciones de entornos, plantillas de infraestructura como código y pipelines de despliegue relacionados. +- **Excluye:** lógica de aplicación en `api/`, `ui/` u otros módulos funcionales, así como configuraciones de CI/CD que no estén bajo `infrastructure/`. + +## 4. Responsables + +| Rol | Responsabilidad | Contacto / canal | +| --- | --- | --- | +| Liderazgo QA | Aprobar hallazgos y planes de remediación | #qa-gobernanza | +| SRE / DevOps | Implementar cambios de estructura y controles técnicos | #sre | +| Seguridad | Validar alineación con requisitos de cumplimiento | #security | + +## 5. Frecuencia + +- Auditoría estructural por cada cambio mayor de infraestructura o trimestral. +- Validación ligera posterior a despliegues significativos. + +## 6. Checklist operativo + +| Paso | Acción | Evidencia esperada | Estado | +| --- | --- | --- | --- | +| Inventario de carpetas críticas | Listar `infrastructure/bin`, `infrastructure/scripts`, `infrastructure/system`, `infrastructure/utils` y subcarpetas por entorno | Registro del árbol, responsables y propietarios | +| Convenciones de nombres | Confirmar prefijos y sufijos coherentes (p. ej., scripts `*.sh` con `set -euo pipefail`) y alineados a `engineering-ruleset.md` | Muestra de archivos revisados y referencias cruzadas | +| Seguridad y permisos en scripts | Validar uso de `SCRIPT_DIR`, ausencia de rutas absolutas rígidas, permisos mínimos (`chmod 750/640`) y dependencias explícitas | Extractos de scripts con controles y salida de `ls -l` | +| Plantillas y configuraciones | Revisar consistencia de archivos de configuración y ambientes (`*-dev.*`, `*-stage.*`, `*-prod.*`), variables obligatorias y valores seguros por defecto | Listado de plantillas, parámetros obligatorios y ejemplos de valores | +| Observabilidad y logs | Confirmar que scripts generan trazas `[INFO]/[WARN]/[ERROR]/[SUCCESS]` y que pipelines capturan logs y artefactos | Capturas o logs generados y rutas de almacenamiento | +| Housekeeping de artefactos | Verificar políticas de retención y limpieza de artefactos/paquetes en pipelines y repositorios de infraestructura | Evidencia de políticas o jobs programados | + +## 7. Métricas + +| Métrica | Definición | Umbral | Fuente | +| --- | --- | --- | --- | +| Scripts conformes | Scripts que cumplen guías de `infrastructure/scripts/AGENTS.md` vs. total auditado | ≥ 95% | Auditoría puntual | +| Pipelines con logging completo | Pipelines que almacenan logs y artefactos accesibles durante ≥ 30 días | ≥ 95% | Plataforma CI/CD | +| Desviaciones corregidas | Hallazgos cerrados dentro del período de revisión | ≥ 90% | Seguimiento de tickets | +| Tiempo de remediación | Promedio de días para corregir hallazgos críticos | ≤ 7 días | Sistema de tickets | + +## 8. Convenciones de nomenclatura + +- Alinear con `docs/standards/engineering-ruleset.md` para reglas generales de carpetas y archivos. +- Scripts Bash en `snake_case.sh` y con cabecera `#!/usr/bin/env bash`; incluir sufijos que describan el objetivo (`-deploy`, `-backup`, `-lint`). +- Plantillas y configuraciones nombradas por entorno (`*-dev.*`, `*-stage.*`, `*-prod.*`) y tecnología (`terraform-`, `ansible-`, `helm-`). +- Directorios por entorno en `infrastructure//` para reflejar los límites de responsabilidad. + +## 9. Registro de decisiones y observaciones + +- Documentar dependencias compartidas entre componentes de infraestructura y riesgos conocidos. +- Registrar excepciones aprobadas a estándares de hardening o logging. + +## 10. Trazabilidad y anexos + +- Enlazar a playbooks, runbooks o pipelines que automaticen validaciones. +- Adjuntar referencias a ADR relevantes cuando las decisiones afecten la arquitectura.