📦 Vendoring Policy - Cuándo y Cómo Internalizar Dependencias¶
🎯 ¿Qué es Vendoring?¶
Vendoring es la práctica de incluir el código fuente de dependencias externas directamente dentro de tu repositorio, en lugar de descargarlas dinámicamente desde package managers.
┌────────────────────────────────────────────────────────────┐
│ │
│ 🔄 FLUJO TRADICIONAL (Sin Vendoring) │
│ │
│ Tu Repo → vcpkg → Internet → Descarga Library │
│ │
│ ⚠️ Riesgo: ¿Y si el upstream desaparece? │
│ │
└────────────────────────────────────────────────────────────┘
┌────────────────────────────────────────────────────────────┐
│ │
│ 📦 FLUJO VENDORING │
│ │
│ Tu Repo → vendored/ → Library Code (incluido) │
│ │
│ ✅ Control: La library SIEMPRE está disponible │
│ │
└────────────────────────────────────────────────────────────┘
⚖️ Trade-offs: Pros vs Contras¶
✅ Ventajas del Vendoring¶
🎯 GARANTÍA DE BUILD¶
- Tu proyecto compila HOY
- Tu proyecto compila en 10 AÑOS
- Incluso si GitHub/vcpkg/upstream desaparecen
- Caso real: Google Code cerró → miles de proyectos rotos
🔧 MODIFICACIONES CUSTOM¶
- Puedes parchar bugs críticos inmediatamente
- Optimizar para tu caso de uso específico
- Agregar features propietarios
- Sin esperar aprobación de upstream
🔒 VERSIÓN CONGELADA¶
- Library v2.0 introduce breaking change
- Tu código vendorizado sigue en v1.8 (estable)
- Actualizas SOLO cuando estés listo
- Control total del timing
❌ Desventajas del Vendoring¶
📈 TAMAÑO DEL REPOSITORIO¶
- Repo sin vendoring: 50 MB
- Repo con JUCE vendorizado: +150 MB
- Repo con múltiples deps: +500 MB
- Git clones más lentos
🔄 RESPONSABILIDAD DE MANTENIMIENTO¶
- Security patch en library → TÚ debes actualizar manualmente
- TÚ eres responsable de merges/conflicts
- Sin vendoring: vcpkg update automático
- Con vendoring: Trabajo manual continuo
🐛 FALTA DE ACTUALIZACIONES AUTOMÁTICAS¶
- CVE crítico publicado
- Sin vendoring: vcpkg upgrade → parcheado
- Con vendoring: Esperas a que TÚ lo actualices
- Ventana de vulnerabilidad más larga
🎯 Criterios de Decisión¶
Matriz de Decisión¶
Alto │ 📦 VENDORIZAR │ 🤔 CONSIDERAR │
│ │ │
Criticidad para ├──────────────────┼──────────────────┤
tu proyecto │ │ │
Bajo │ ✅ NO VENDORIZAR │ ✅ NO VENDORIZAR │
│ │ │
└──────────────────┴──────────────────┘
Baja Alta
Probabilidad de necesitar modificarlo
📦 SÍ Vendorizar cuando:¶
1. Dependencia CRÍTICA del core - Ejemplo: DSP library custom que define tu sonido - Riesgo: Library desaparece = Producto no compila
2. Necesitas modificaciones frecuentes - Ejemplo: JUCE con patches custom de rendimiento - Beneficio: Modificas directamente en vendored/
3. Library no está en package managers - Ejemplo: SDK propietario de hardware - Sin proceso de instalación estandarizado
4. Versión específica CONGELADA requerida - Ejemplo: Dependes de API deprecated - Library v2.0 elimina APIs que usas
✅ NO Vendorizar cuando:¶
1. Library bien mantenida en package managers - Ejemplo: fmt, spdlog, Catch2 - Updates automáticos con vcpkg - Security patches inmediatos
2. Dependencies grandes que rara vez cambias - Ejemplo: Boost, Qt, JUCE (si no modificas) - +500 MB al repositorio sin beneficio real
3. Libraries de sistema operativo - Ejemplo: ALSA (Linux), CoreAudio (macOS) - Ya están en el sistema - Vendorizar causa conflictos
4. Dependencies experimentales o temporales - Probando diferentes libraries - Mejor: vcpkg manifest mode - Vendoriza solo cuando decisión final
📋 Policy de AudioLab¶
Decisiones Estratégicas¶
📦 VENDORIZAR (vendored/) 1. DSP Core Algorithms (crítico para sonido) - Si desarrollamos algorithms propietarios 2. Hardware SDK custom - Si integramos con hardware específico 3. Patches a JUCE (si necesarios) - Solo patches críticos de performance - Documentar cada patch
✅ VCPKG (gestión externa) 1. JUCE Framework (si no modificado) 2. fmt, spdlog (utilities) 3. Catch2, benchmark (testing) 4. FFTW3 (si no usamos IPP) 5. Cualquier library estándar bien mantenida
🔄 Proceso de Vendoring¶
Workflow Completo¶
- DECISIÓN
- Evaluar según criterios
-
Aprobación: Tech lead + 1 reviewer
-
DESCARGA ORIGINAL
- Descargar source code de versión específica
- Verificar checksums / GPG signatures
-
Documentar provenance
-
COLOCACIÓN
- Ubicar en:
vendored/<library-name>/ - Mantener estructura original
-
NO modificar aún
-
DOCUMENTACIÓN
- Crear:
vendored/<library>/README_VENDOR.md -
Incluir: versión, URL, razón, licencia, maintainer
-
INTEGRACIÓN CMAKE
- Agregar:
add_subdirectory(vendored/<library>) -
Verificar que compila
-
PATCHES (si necesario)
- Aplicar modificaciones
- Generar .patch file
-
Guardar en:
patches/<library>/001-descripcion.patch -
COMMIT
- Commit separado con mensaje claro
- Ejemplo: "vendor: Add libDSP v2.3.1 for FFT"
📁 Estructura de Directorio¶
03_03_05_vendoring/
├─ vendored/ ← Código vendorizado
│ ├─ libDSP/ ← Ejemplo: Library custom
│ │ ├─ src/
│ │ ├─ include/
│ │ ├─ CMakeLists.txt
│ │ ├─ LICENSE
│ │ └─ README_VENDOR.md ← OBLIGATORIO
│ └─ hardware_sdk/ ← Ejemplo: SDK propietario
│ └─ README_VENDOR.md
│
├─ patches/ ← Patches aplicados
│ └─ libDSP/
│ ├─ 001-fix-simd-alignment.patch
│ ├─ 002-optimize-fft.patch
│ └─ README.md ← Explica cada patch
│
├─ VENDOR_POLICY.md ← Este documento
├─ update_vendored.ps1 ← Script actualización
└─ verify_vendored.ps1 ← Verifica integridad
🔄 Mantenimiento¶
Calendario de Revisión¶
🔴 CRÍTICO: Security updates - Frecuencia: Inmediato (cuando publicado) - Proceso: Evaluar → Update <48h → Deploy
🟡 IMPORTANTE: Bug fixes - Frecuencia: Mensual - Proceso: Review changelog → Testing → Merge si estable
🟢 OPCIONAL: Feature updates - Frecuencia: Quarterly - Proceso: Evaluar features → Planning → Update coordinado
⚠️ Señales de Alerta¶
Considerar des-vendorizar si:¶
- ❌ Library ahora disponible en vcpkg/conan
- ❌ No has modificado la library en 1+ año
- ❌ Team no tiene capacidad de mantener updates
- ❌ Tamaño del repo es problema (>1 GB)
✅ Checklist Pre-Vendoring¶
- ¿Es dependencia CRÍTICA?
- ¿No disponible en package managers?
- ¿Necesitas modificarla frecuentemente?
- ¿Team tiene capacidad de mantenerla?
- ¿Tamaño es razonable (<50 MB)?
- ¿Licencia permite redistribución?
- ¿Documentación de upstream es clara?
- ¿Existe plan de actualización?
- ¿Tienes approval de tech lead?
- ¿README_VENDOR.md preparado?
Si 7+ son ✅ → Procede con vendoring Si 5-6 son ✅ → Considera alternativas Si <5 son ✅ → NO vendorizar
Última actualización: 2025-10-03