Runbook para Actualización de Dependencias

Visión General

Las dependencias desactualizadas exponen los proyectos a vulnerabilidades de seguridad, problemas de compatibilidad y funcionalidades faltantes. Este runbook proporciona un proceso repetible para actualizar dependencias de forma segura con un riesgo mínimo.

Cuándo Usar

Usa este recurso cuando:

• Se publique un parche de seguridad crítico para una dependencia directa o transitiva
• Se requieran actualizaciones de versiones mayores para soporte a largo plazo
• Haya ventanas de mantenimiento trimestrales o por sprint para actualizar dependencias

Solución

# Runbook de Actualización de Dependencias

## 1. Preparación

- [ ] Identificar la dependencia y la versión objetivo
- [ ] Revisar el changelog / notas de la versión en busca de cambios incompatibles
- [ ] Comprobar issues abiertos en el repositorio de la dependencia relacionados con la actualización
- [ ] Crear una rama dedicada: `deps/upgrade-<nombre>-<version>`
- [ ] Asegurar que el CI esté verde en la rama principal actual

## 2. Actualización

- [ ] Actualizar la versión en `package.json`, `requirements.txt`, `pom.xml`, etc.
- [ ] Ejecutar el comando de instalación de dependencias
- [ ] Revisar advertencias de dependencias peer o conflictos
- [ ] Ejecutar pruebas automatizadas (unitarias, integración, lint)
- [ ] Ejecutar pruebas de humo contra un entorno local o staging

## 3. Validación

- [ ] Revisar informes de cobertura de pruebas en busca de regresiones
- [ ] Comprobar logs de la aplicación en busca de nuevas advertencias o errores
- [ ] Verificar rutas críticas del usuario manualmente si cambió el comportamiento
- [ ] Ejecutar escaneo de seguridad (`npm audit`, `safety check`, OWASP dependency check)

## 4. Plan de Reversión

- [ ] Etiquetar el último commit conocido como bueno antes del merge
- [ ] Documentar cualquier cambio manual de datos o configuración requerido
- [ ] Confirmar que la reversión puede ejecutarse en 15 minutos

## 5. Merge y Monitoreo

- [ ] Abrir un pull request con resumen del changelog
- [ ] Desplegar en staging y dejarlo madurar por 24 horas
- [ ] Desplegar en producción durante una ventana de bajo tráfico
- [ ] Monitorear tasas de error y latencia durante 48 horas después del despliegue

Explicación

El runbook divide las actualizaciones en cinco fases para reducir el riesgo. La preparación evita sorpresas revisando changelogs. La fase de Actualización aísla los cambios en una rama. La Validación usa pruebas automatizadas y manuales. El Plan de Reversión garantiza una recuperación rápida. Merge y Monitoreo completa el ciclo con observación en producción.

Variantes

Contexto	Enfoque	Notas
Parche de seguridad	Rama de vía rápida	Omitir tiempo de maduración solo para CVEs con exploits activos
Versión mayor	Despliegue con feature flags	Aislar nuevo comportamiento bajo banderas durante la transición
Monorepo	Actualizaciones en lote	Actualizar librerías compartidas primero, luego los consumidores

Mejores Prácticas

1. Actualizar una dependencia mayor a la vez para simplificar la depuración
2. Fijar versiones exactas en archivos de bloqueo (package-lock.json, poetry.lock) y commitearlos
3. Usar herramientas automatizadas como Dependabot o Renovate para parches y menores
4. Mantener un calendario de deprecación para dependencias en fin de vida
5. Documentar todos los cambios incompatibles y pasos de migración en el pull request

Errores Comunes

1. Actualizar múltiples dependencias mayores simultáneamente, haciendo difícil atribuir fallos
2. Ignorar advertencias de dependencias peer que causan errores en tiempo de ejecución
3. Omitir el plan de reversión, extendiendo el tiempo de inactividad cuando surgen problemas
4. No revisar cambios de dependencias transitivas en archivos de bloqueo
5. Desplegar durante tráfico pico sin un período de maduración

Preguntas Frecuentes

¿Con qué frecuencia debo actualizar las dependencias?

Versiones de parche: semanalmente o automatizado. Versiones menores: mensualmente. Versiones mayores: trimestralmente o cuando se requiera.

¿Qué pasa si una dependencia transitiva tiene un CVE?

Usa npm audit fix, pip-audit, o campos de override/resolution para forzar una versión transitiva parcheada sin esperar a la dependencia directa.

¿Debo commitear los archivos de bloqueo?

Sí. Los archivos de bloqueo aseguran builds reproducibles entre entornos y hacen los diffs revisables durante las actualizaciones.