Actualizar una dependencia de forma segura
Objetivo: mover una dependencia (o un grupo estrechamente acoplado) a una versión más nueva, comprendiendo los cambios disruptivos de antemano, no descubriéndolos después.
Plan
- Determina el estado actual. Encuentra la versión instalada (archivo de bloqueo, no solo el manifiesto) y la versión objetivo. Si el usuario dijo "última", búscala con el administrador de paquetes (
npm view <paquete> version,pip index versions <paquete>,cargo search, etc.) e indica el número. - Registra una línea base en un árbol de trabajo limpio: instala, compila, prueba, lint y verificación de tipos. Anota cualquier fallo preexistente para no culpar a la actualización.
- Lee las notas de la versión reales. Abre el registro de cambios, las notas de la versión o la guía de migración para cada versión entre la actual y la objetivo. Extrae: cambios disruptivos, APIs eliminadas o renombradas, nuevas versiones mínimas de entorno, valores predeterminados modificados, deprecaciones. Cita el enlace de origen para cada elemento. Si no puedes encontrar notas de la versión, indícalo y trata la actualización como de mayor riesgo.
- Mapea el impacto. Usa
rgen el código base para cada API eliminada, renombrada o modificada. Enumera los archivos afectados antes de editar.
Ejecutar
- Actualiza solo esta dependencia (y sus pares requeridos). No ejecutes una "actualización masiva".
- Actualiza el manifiesto y el archivo de bloqueo con el administrador de paquetes del proyecto, no a mano.
- Realiza los cambios de código que requieran las notas, comenzando por los más pequeños. Reemplaza los usos obsoletos cuando la nueva forma sea equivalente.
- Ejecuta instalación, compilación, pruebas, lint y verificación de tipos nuevamente. Compara con la línea base.
- Para versiones principales, también ejecuta la aplicación o la ruta de ejemplo principal si es factible, y verifica el tamaño del bundle, las advertencias de inicio y las advertencias de deprecación.
- Si la actualización requiere un cambio en la versión mínima del entorno o de los pares, detente y pregunta antes de modificarlo.
Reporte
Actualización: <paquete> <desde> -> <hasta>
Fuentes: <enlaces a registros de cambios>
Cambios disruptivos aplicados: <lista con referencias a archivos>
Cambios realizados: <resumen>
Verificación: <comandos, línea base vs. después>
Advertencias o seguimientos: <deprecaciones, elementos omitidos, riesgos>
Revertir: deshacer <archivos> o `git revert <commit>`
Reglas
- Nunca actualices y refactorices en el mismo cambio.
- Nunca omitas una prueba fallida ni aflojes un rango de versión para ocultar un problema.
- Correcciones de seguridad: menciona qué aviso de seguridad soluciona la actualización solo si lo viste en un aviso oficial o en las notas de la versión.
- Si una dependencia transitiva fuerza un conflicto, muestra la salida del conflicto y propón opciones en lugar de sobrescribir a ciegas.