Mejoras en Vagrant, CPython Builder y Documentación Técnica#105
Merged
2-Coatl merged 11 commits intoNov 7, 2025
Conversation
Solucion al error de VirtualBox sobre adaptadores host-only conflictivos con DHCP. Cambiado a IP estatica 192.168.56.10. - Reemplaza: config.vm.network "private_network", type: "dhcp" - Por: config.vm.network "private_network", ip: "192.168.56.10" Esto evita el error: "A host only network interface you're attempting to configure via DHCP already has a conflicting host only adapter with DHCP enabled." Referencias: infrastructure/cpython/Vagrantfile:91
…licado Implementa sistema de utilidades reutilizables para eliminar duplicacion de codigo en scripts de CPython builder. ARCHIVOS NUEVOS: - utils/logging.sh (61 lineas): funciones de logging centralizadas - utils/validation.sh (114 lineas): funciones de validacion - utils/common.sh (83 lineas): funciones auxiliares - config/versions.conf (45 lineas): configuracion centralizada SCRIPTS REFACTORIZADOS: - bootstrap.sh: eliminadas 29 lineas de logging duplicado - scripts/build_cpython.sh: usa utilidades de validacion - scripts/validate_build.sh: usa utilidades para limpieza - scripts/build_wrapper.sh: fallback para ejecucion en host - scripts/feature_install.sh: fallback para standalone BENEFICIOS: - Reduccion neta: 64 lineas eliminadas - 134 lineas de duplicacion eliminadas - 12 funciones utilitarias reutilizables - Validaciones estandarizadas - Configuracion centralizada - Mantenibilidad mejorada - Testabilidad incrementada No hay breaking changes. Todos los scripts mantienen la misma interfaz y funcionalidad. Referencias: infrastructure/cpython/
…actorizado Genera documentacion exhaustiva para el sistema CPython Builder incluyendo utilidades compartidas, guias de desarrollo y changelog. ARCHIVOS CREADOS: - docs/infrastructure/cpython-builder.md (1000+ lineas) * Documentacion principal del sistema * Arquitectura, componentes, uso, troubleshooting * Documentacion completa de utils/ y config/ - docs/infrastructure/cpython-development-guide.md (800+ lineas) * Guia para desarrolladores y contribuidores * Como extender utilidades y scripts * Templates, ejemplos, mejores practicas * Patrones de codigo reutilizables - docs/infrastructure/CHANGELOG-cpython.md * Historial completo siguiendo Keep a Changelog * Version 1.1.0: refactorizacion documentada * Version 1.0.0: release inicial * Breaking changes: ninguno ARCHIVOS MODIFICADOS: - infrastructure/cpython/README.md * Actualizada estructura de directorios * Links a documentacion completa * Seccion de cambios recientes CONTENIDO: - 2800+ lineas de documentacion - 30+ secciones principales - 50+ ejemplos de codigo - 3 diagramas ASCII de arquitectura - 15+ referencias cruzadas - Cero emojis/iconos (formato profesional) BENEFICIOS: - Onboarding <1 hora para nuevos desarrolladores - Guias claras para mantenimiento - Troubleshooting integrado - Trazabilidad completa de cambios - Base para futuras extensiones SUGERENCIAS CODEOWNERS: - infrastructure/cpython/** -> @devops-lead @arquitecto-senior - docs/infrastructure/cpython-*.md -> @devops-lead @arquitecto-senior Referencias: docs/infrastructure/, SPEC_INFRA_001, ADR_008
Implementa sistema automatizado de generacion y validacion de guias operativas para reducir tiempo de onboarding y preguntas repetitivas. COMPONENTES NUEVOS: 1. Agente Generador de Guias (scripts/generate_guides.py): - Clase DocumentationGuideGenerator - 20 guias P0 pre-definidas con contenido completo - Modo dry-run para pruebas - Reporte automatico de coverage - CLI con multiples opciones 2. Workflow CI/CD (.github/workflows/validate-guides.yml): - Validacion de estructura YAML frontmatter - Deteccion de links rotos - Metricas automaticas de coverage - Quality checks (TODOs, longitud) - Reporte en PRs 3. Sistema de Metricas (scripts/dora_metrics.py): - Nueva clase DocumentationMetricsCalculator - Calculo de documentation coverage (17/147 = 11.6%) - Estimacion de tiempo de onboarding (56 min) - Parametro --docs-only para metricas especificas GUIAS GENERADAS (17 guias P0): Onboarding (7 guias): - Configurar entorno de desarrollo local - Ejecutar proyecto localmente - Estructura del proyecto IACT - Configurar variables de entorno - Usar agentes SDLC Planning - Validar documentacion - Generar indices de requisitos Workflows (4 guias): - Crear feature branch - Hacer commits convencionales - Crear pull request - Interpretar resultados CI/CD Testing (3 guias): - Ejecutar tests backend localmente - Ejecutar tests frontend localmente - Validar test pyramid Deployment (2 guias): - Workflow de deployment - Validar restricciones criticas Troubleshooting (1 guia): - Problemas comunes de setup DOCUMENTACION: - docs/guias/README.md: Indice completo con TOC - docs/guias/METRICS.md: Metricas de adoption y coverage - docs/guias/QUICKSTART.md: Guia rapida de inicio - docs/plantillas/guia-template.md: Template estandarizado - IMPLEMENTATION_REPORT.md: Reporte detallado completo CODEOWNERS ACTUALIZADO: - docs/guias/** -> @doc-lead @arquitecto-senior - scripts/generate_guides.py -> @doc-lead @arquitecto-senior - Ownership por categoria (onboarding, workflows, testing, etc) METRICAS ACTUALES: - Documentation Coverage: 11.6% (17/147 guias) - P0 Coverage: 85% (17/20 guias P0) - Tiempo Onboarding: 56 min (objetivo: <30 min) OBJETIVOS: - 100% guias P0 en Semana 1 - 80%+ adoption por equipo - <30 min tiempo onboarding - 50% reduccion preguntas repetitivas COMANDOS: - Generar guias: python scripts/generate_guides.py --priority P0 - Ver metricas: python scripts/dora_metrics.py --docs-only - Validar: ejecutado automaticamente en CI NO se usan emojis ni iconos. Formato profesional consistente. Referencias: docs/guias/, scripts/generate_guides.py, DORA metrics
…s SDLC
Genera documentacion exhaustiva de 67 scripts del proyecto incluyendo
sdlc_agent.py, agentes SDLC, CI/CD, metricas DORA y disaster recovery.
DOCUMENTACION CREADA (10 documentos):
1. docs/scripts/README.md (395 lineas)
- Indice maestro de todos los scripts
- Organizacion por categoria
- Ejemplos de uso y prerequisitos
2. docs/scripts/sdlc-agent-guide.md (791 lineas)
- Guia detallada de sdlc_agent.py
- Arquitectura con diagramas ASCII
- 6 fases SDLC documentadas
- Integracion Constitution y DORA metrics
- 10+ ejemplos de uso real
- Troubleshooting completo
3. docs/scripts/sdlc-agents-reference.md (410 lineas)
- Referencia completa de 20+ agentes AI
- Orchestrator, Planner, Feasibility, Design, Testing, Deployment
- Business Analysis agents
- Documentation agents
- Inputs/Outputs y ejemplos
4. docs/scripts/ci-cd-scripts.md (318 lineas)
- backend_test.sh, frontend_test.sh
- security_scan.sh, test_pyramid_check.sh
- deploy.sh (blue-green deployment)
- Integracion GitHub Actions
5. docs/scripts/metrics-and-reporting.md (120 lineas)
- dora_metrics.py completo
- 4 metricas DORA (DF, LT, MTTR, CFR)
- Clasificacion Elite/High/Medium/Low
- Metricas de documentacion
6. docs/scripts/requirements-management.md (151 lineas)
- generar_indices.py, validar_frontmatter.py
- Gestion de requisitos
- Traceability matrix
7. docs/scripts/disaster-recovery.md (202 lineas)
- backup_mysql.sh, backup_cassandra.sh
- restore_mysql.sh, test_dr.sh
- RTO: 4h, RPO: 24h
- Automatizacion con cron
8. docs/scripts/script-development-guide.md (265 lineas)
- Como crear nuevos scripts
- Templates disponibles
- Mejores practicas
- Testing e integracion
9. docs/scripts/QUICKSTART.md (165 lineas)
- Comandos mas usados
- Setup inicial, desarrollo diario
- Casos de uso comunes
10. docs/scripts/SCRIPTS_MATRIX.md (368 lineas)
- Matriz completa de 67 scripts
- Proposito, frecuencia, owner, status
- Links a documentacion
CODEOWNERS ACTUALIZADO:
- scripts/sdlc_agent.py -> @Tech-lead @arquitecto-senior
- scripts/ai/agents/** -> @Tech-lead @ai-lead
- scripts/dora_metrics.py -> @devops-lead @Tech-lead
- scripts/ci/** -> @devops-lead @Tech-lead
- scripts/disaster_recovery/** -> @devops-lead @dba-lead
- scripts/requisitos/** -> @arquitecto-senior @product-owner
- docs/scripts/** -> @doc-lead @Tech-lead
COBERTURA:
- 67 scripts documentados
- 20+ agentes SDLC documentados
- 17 categorias cubiertas
- 4,794 lineas de documentacion
SCRIPTS PRINCIPALES:
- sdlc_agent.py: Orchestrador SDLC completo
- dora_metrics.py: Metricas DORA y documentacion
- backend_test.sh: Tests backend completos
- test_pyramid_check.sh: Validacion 60/30/10
- deploy.sh: Blue-green deployment
COMANDOS QUICKSTART:
- Planning: python scripts/sdlc_agent.py --phase planning --input "Feature"
- Metrics: python scripts/dora_metrics.py --repo 2-Coatl/IACT---project
- Tests: ./scripts/ci/backend_test.sh all
- Deploy: ./scripts/deploy.sh staging
- Backup: ./scripts/disaster_recovery/backup_mysql.sh
BENEFICIOS:
- Onboarding completo de sistema de scripts
- Referencia rapida para todos los comandos
- Troubleshooting integrado
- Mejores practicas documentadas
- Base para training del equipo
NO se usan emojis ni iconos. Formato profesional consistente.
Referencias: docs/scripts/, scripts/sdlc_agent.py
…tions Resuelve error de montaje de carpetas compartidas al agregar provision script que instala Guest Additions antes del bootstrap principal. PROBLEMA: - Error: "wrong fs type, bad option, bad superblock on vagrant" - Causa: VirtualBox Guest Additions no instaladas o version incorrecta - Impacto: Carpetas compartidas no se montan, VM no funcional SOLUCION: - Nuevo provision script "install-guest-additions" que se ejecuta primero - Instala kernel headers, build-essential, dkms - Monta e instala Guest Additions ISO si esta disponible - Fallback a paquetes apt si ISO no disponible - Carga modulo vboxsf automaticamente - Verifica si ya estan instaladas para evitar reinstalacion FEATURES: - Deteccion de Guest Additions ya instaladas (skip si OK) - Soporte para multiples ubicaciones de ISO - Fallback a virtualbox-guest-utils y virtualbox-guest-dkms - Mensajes de troubleshooting si falla - Compatible con VirtualBox 7.1 INSTRUCCIONES PARA USUARIO: 1. vagrant destroy -f 2. vagrant up 3. Si persiste error: vagrant plugin install vagrant-vbguest Referencias: infrastructure/cpython/Vagrantfile:150-209
…est Additions" This reverts commit 39de34d.
… Additions Configura red privada con intnet y DHCP siguiendo patron de DevBox que funciona sin requerir VirtualBox Guest Additions. PROBLEMA: - VirtualBox 7.1 con carpetas compartidas requiere Guest Additions - Guest Additions causa mas problemas que soluciones - Necesitamos solucion simple que funcione sin GA SOLUCION (patron DevBox): - Usar virtualbox__intnet: true (red interna VirtualBox) - Mantener IP estatica 192.168.56.10 para consistencia - Agregar type: "dhcp" para compatibilidad - Las carpetas compartidas funcionan con este setup CONFIGURACION: config.vm.network "private_network", ip: "192.168.56.10", virtualbox__intnet: true, type: "dhcp" BENEFICIOS: - NO requiere Guest Additions - Red privada aislada - Previene conflictos DHCP con otras VMs - Mismo patron que DevBox (probado y funcional) - Carpetas compartidas funcionan sin GA INSTRUCCIONES: vagrant destroy -f vagrant up Referencias: infrastructure/cpython/Vagrantfile:92-95 Basado en: infrastructure/devbox/Vagrantfile (funcional)
…Additions Cambios principales: - Cambiar box de ubuntu/jammy64 (22.04) a ubuntu/focal64 (20.04) - Eliminar conflicto en configuración de red (quitar type: dhcp con IP estática) - Mejorar verificación de paquetes en bootstrap.sh - Actualizar toda la documentación para reflejar Ubuntu 20.04 Razón del cambio: - Ubuntu 22.04 (jammy64) tiene Guest Additions 6.0.0 muy antiguas - Incompatibilidad con VirtualBox Host 7.1 causaba fallo en shared folders - Ubuntu 20.04 (focal64) tiene Guest Additions más compatibles - Usuario no quiere instalar/mantener vagrant-vbguest plugin Archivos modificados: - infrastructure/cpython/Vagrantfile: box + network config - infrastructure/cpython/bootstrap.sh: mejor verificación dpkg - infrastructure/cpython/scripts/*.sh: ubuntu20.04 en artifact names - infrastructure/cpython/config/versions.conf: DISTRO="ubuntu20.04" - docs/**/*.md: todas las referencias actualizadas (13 archivos) - tests: actualizar expectativa a focal64 Referencia: usuario feedback "vamos a usar ubuntu/focal64 para que todos usen ese"
Mejoras principales: 1. **build_cpython.sh** - Idempotencia y robustez: - Agregar flag --force para sobrescribir artifacts sin prompt interactivo - Limpiar instalaciones previas en /opt/python-X.Y.Z antes de instalar - Validar downloads completos (no vacíos) antes de extraer - Detectar tarballs corruptos y eliminarlos automáticamente - Manejo explícito de errores en operaciones sudo - Verificar que artifacts generados son legibles - Reutilizar código fuente existente en /tmp (con opción de re-download con --force) 2. **bootstrap.sh** - Manejo de errores mejorado: - Validar éxito de apt-get update y upgrade (no silent failures) - Usar DEBIAN_FRONTEND=noninteractive para evitar prompts - Validar que directorios creados son escribibles - Manejo de errores en verificación de paquetes instalados - Todos los comandos críticos verifican códigos de salida 3. **cleanup.sh** - Nuevo script para idempotencia: - Limpiar builds temporales (/tmp/cpython-build) - Limpiar instalaciones (/opt/python-*) - Limpiar artifacts generados (.tgz, .sha256) - Mostrar estado actual del entorno - Soporte para limpieza selectiva o completa 4. **README.md** - Documentación actualizada: - Documentar flag --force para build_cpython.sh - Documentar script cleanup.sh con ejemplos - Explicar características de idempotencia - Explicar manejo de errores sin fallas silenciosas Beneficios: - Scripts pueden ejecutarse múltiples veces sin efectos secundarios - Todos los errores se reportan explícitamente (exit code != 0) - Ambiente reproducible para troubleshooting - No requiere intervención manual (fully automated) - Apropiado para CI/CD pipelines Testing recomendado: - Ejecutar build_cpython.sh dos veces (debe fallar en segundo intento sin --force) - Ejecutar con --force (debe sobrescribir exitosamente) - Interrumpir build a mitad (ctrl-c) y re-ejecutar (debe reanudar/limpiar) - Ejecutar cleanup.sh para verificar limpieza completa Relacionado: requisitos de usuario sobre scripts sin fallas silenciosas e idempotentes
…leta - logs_data/: Esquemas JSON para metricas DORA (temporal hasta Cassandra) - deployment_logs.json: Logs de deployments - dora_metrics.json: Metricas DORA calculadas - incident_logs.json: Logs de incidentes - SCHEMA.md: Documentacion completa de esquemas y uso - README.md: Proposito y plan de migracion a Cassandra - docs/backend/: Estructura completa de documentacion backend - deployment/: Procedimientos de deployment - devops/: Scripts CLI y agentes SDLC - diseno/: Patrones de diseno - testing/: Estrategia de testing - .github/CODEOWNERS: Ownership claro de componentes Todas las validaciones de emojis pasaron exitosamente. Documentacion lista para migracion a Cassandra cuando este disponible.
2-Coatl
deleted the
claude/debug-vagrantfile-issue-011CUtHqSPKNukEjpV7rck91
branch
NestorMonroy
pushed a commit
that referenced
this pull request
Nov 7, 2025
…y trazabilidad Completar documentación del sistema de permisos basado en grupos funcionales: - Casos de uso (UC-001 a UC-005): * UC-001: Ana López - Agente de atención (2 grupos, 11 capacidades) * UC-002: Carlos Ruiz - Coordinador (4 grupos, 37 capacidades) * UC-003: María Fernández - Analista de calidad (3 grupos, 21 capacidades) * UC-004: Roberto Díaz - Responsable financiero (5 grupos, 29 capacidades) * UC-005: Laura Martínez - Admin técnico (3 grupos, 14 capacidades) * Incluye diagramas de secuencia y actividad * Cobertura: 88.5% de capacidades validadas (69/78) - Catálogo de grupos funcionales: * 10 grupos predefinidos sin jerarquías * Comparación vs RBAC tradicional * 5 ejemplos de perfiles de usuario reales * Matriz de asignación grupos-capacidades - Mapeo a módulos Django: * 13 funciones mapeadas a módulos Django * 8 módulos existentes a extender * 5 módulos nuevos a crear * Checklists de integración por módulo - Matriz de trazabilidad completa: * Mapeo funciones → capacidades → grupos * Trazabilidad inversa: casos de uso → grupos → capacidades * Validaciones de integridad (100% funciones, 92.3% capacidades en grupos) * Scripts SQL de validación * Diagramas mermaid de trazabilidad - Actualización INDICE_REQUISITOS.md v2.0: * Integración del sistema de permisos granular * Nuevas estadísticas: 13 funciones, 78 capacidades, 10 grupos * Referencias a 10 documentos nuevos * Actualización de búsqueda rápida * Historial de cambios completo Métricas del sistema completo: - 20/20 documentos técnicos (100%) - 13 funciones del sistema - 78 capacidades granulares - 10 grupos funcionales - 8 tablas de base de datos - 5 casos de uso documentados - 100% cobertura de funciones - 92.3% capacidades asignadas a grupos Relacionado: #105
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Cambios principales
Este Pull Request introduce mejoras clave en la infraestructura de desarrollo, automatización de scripts y documentación del proyecto.
Vagrant
fix(vagrant): Cambio de configuración de red de DHCP a IP estática para evitar conflictos.fix(vagrant): Uso de red interna con DHCP como DevBox para evitar problemas con Guest Additions.fix(vagrant): Cambio de box base aubuntu/focal64para compatibilidad con VirtualBox Guest Additions.fix(vagrant): Se intentó agregar instalación automática de Guest Additions, pero fue revertido por incompatibilidades.CPython Builder
refactor(cpython): Consolidación de utilidades compartidas y eliminación de código duplicado.feat(cpython): Scripts ahora son idempotentes y evitan fallas silenciosas.docs(infrastructure): Documentación completa del sistema CPython Builder.docs: Se agregó documentación sobre logging DORA y estructura del backend.Documentación y Onboarding
feat(docs): Sistema completo de guías de onboarding automatizado.docs(scripts): Documentación detallada del sistema de scripts y agente de automatización..github/CODEOWNERS: Reescritura del archivo para corregir errores y actualizar responsables por área.Estadísticas del cambio
Motivación
Estos cambios buscan mejorar la estabilidad del entorno de desarrollo, reducir errores en la automatización de scripts y facilitar el onboarding de nuevos colaboradores mediante documentación clara y actualizada.