Cambiar un paquete de servidor público que otros amplían sin romper su código

## Revisar qué se publica y dejar fuera los secretos Antes de editar, identifique el destino de publicación, la licencia, el sistema de módulos, el lenguaje, la función en tiempo de ejecución y la ruta de sincronización del paquete. Trate todos los archivos de un paquete sincronizado públicamente como contenido de publicación, aunque el desarrollo se realice en un espacio de trabajo privado. - Nunca coloque secretos, comportamientos restringidos por licencia ni accesorios de prueba de uso exclusivamente interno dentro del paquete público. - Mantenga sin interfaz gráfica los paquetes exclusivos del servidor; no introduzca dependencias del navegador ni del DOM. - Respete las convenciones reales de módulos y lenguaje del paquete, en lugar de importar patrones de paquetes vecinos. - Registre los dependientes directos del espacio de trabajo y suponga que existen otros consumidores externos del paquete. La distribución pública amplía el alcance del impacto, aunque solo sea visible un dependiente dentro del espacio de trabajo. ## Mantener los callbacks antiguos y las rutas de importación profundas No modernice de forma silenciosa las funciones de devolución de llamada en promesas ni en funciones async. En código que mezcla distintas épocas, un gancho de extensión puede depender de la forma de la función de devolución de llamada, aunque los puntos de llamada cercanos sean síncronos o se basen en promesas. Antes de cambiar una invocación: 1. Enumere todas las implementaciones del punto de extensión. 2. Compare el orden de los argumentos, el comportamiento de retorno, el momento de ejecución de la función de devolución de llamada y la semántica de los errores. 3. Adopte el estilo del archivo que se modifica. 4. Añada o actualice pruebas para cada forma de invocación compatible. No cambie el nombre ni la ubicación de archivos de utilidades, middleware o modelos que parezcan internos hasta haber buscado importaciones profundas en los repositorios descendentes. Una importación mediante una ruta de código fuente es una API pública implícita y puede romperse sin que el compilador emita una advertencia. ## Respetar el orden del middleware y los nombres exactos de los hooks Conserve explícitamente las dependencias del middleware. La autenticación o la resolución de tokens debe ejecutarse antes de las comprobaciones de permisos cuando la autorización lee el contexto de usuario ya rellenado. Trate los cambios de orden como cambios de contrato, no como una limpieza de formato. Para un middleware nuevo, reproduzca la forma de fábrica establecida en el paquete, como una fábrica consciente del paquete que devuelve un gestor de solicitudes, y regístrelo en el punto previsto de la cadena central. Use el mecanismo existente de ganchos de modificación como superficie de extensión. Busque todos los nombres e implementaciones actuales de ganchos antes de añadir un punto de llamada. Confirme el nombre exacto, el valor de entrada, la forma de la devolución de llamada o del valor devuelto y el comportamiento predeterminado; un nombre de gancho mal escrito puede devolver silenciosamente el valor predeterminado. Documente cada nuevo punto de extensión donde puedan encontrarlo los implementadores descendentes. ## Añadir migraciones nuevas en vez de editar las ya publicadas Siga las abstracciones base establecidas en lugar de inventar patrones paralelos. Los modelos de datos nuevos deben usar el complemento de modelo compartido o la forma base. Los recursos REST nuevos de nivel superior deben extender la base de recursos común y registrar las rutas mediante el punto de entrada central. Trate las migraciones de bases de datos ya distribuidas como inmutables y unidireccionales: - nunca edite una migración existente después de su publicación; - añada una migración numerada nueva para cada corrección posterior; - haga que cada migración sea idempotente; - contemple las interrupciones y la ejecución repetida durante el inicio; - verifique el comportamiento tanto en bases de datos nuevas como en las que ya han sido migradas. Cuando los paquetes descendentes inyecten campos o comportamientos de modelos mediante ganchos, audite esos puntos de inyección antes de cambiar esquemas, valores predeterminados, serialización o hidratación. ## Buscar los paquetes afectados por un cambio y probar ambos lados Relacione un cambio con sus consumidores antes de implementarlo. Coordínese con los llamadores descendentes cuando cambie el middleware de autenticación, la gestión de permisos, los límites de sesión, las utilidades compartidas, los auxiliares de cifrado, los ganchos de modelos o las firmas de puntos de extensión. Trate los auxiliares importados desde rutas profundas como API públicas. Trate la propiedad de los tokens frente a la de las sesiones como un límite arquitectónico. Cuando un valor se almacene como referencia y se hidrate al leerlo, audite tanto el escritor como el procesador de desreferenciación antes de cambiar su representación. Para cada modificación transversal: 1. Lea las notas pertinentes de arquitectura, dependencias y problemas conocidos. 2. Busque las implementaciones y los puntos de llamada descendentes. 3. Indique el contrato que debe seguir cumpliéndose. 4. Pruebe ambos lados del límite. 5. Documente cualquier cambio intencionado del contrato y su ruta de migración. ## Probar los valores que cruzan el límite de la máquina virtual Los cambios en los artefactos empaquetados de la máquina virtual, las capas de compatibilidad, las instancias del evaluador, los límites de recursos o la semántica de errores requieren una auditoría completa del contrato entre cliente y servidor. Mantenga equivalentes las capas del anfitrión y del entorno aislado, reconstruya el artefacto empaquetado y verifique que los valores sobrevivan al límite del entorno de ejecución. No suponga que los objetos activos de la base de datos conservan su identidad o sus prototipos después de serializarse mediante un entorno de ejecución aislado. Pruebe identificadores, referencias, fechas, búferes, errores y valores hidratados en ambas direcciones. Preste atención a las mutaciones del anfitrión que afectan a todo el proceso y que pueden causar las capas de compatibilidad inicializadas al cargar el módulo. Un contexto de navegador simulado puede crear un estado global aunque el paquete deba permanecer sin interfaz gráfica. Trate el código del artefacto empaquetado excluido de la cobertura como una carencia de pruebas conocida y añada comprobaciones de ejecución específicas, en lugar de suponer que la cobertura normal lo demuestra. ## Detectar al arrancar las funciones de la base de datos y tener una alternativa Admita varias implementaciones de bases de datos mediante el sondeo de capacidades durante el inicio. Condicione la intercalación avanzada, las canalizaciones de búsqueda, los índices compuestos de rutas anidadas y otras funciones que superen la base mínima al resultado del sondeo, y distribuya una alternativa probada. Nunca deduzca la compatibilidad a partir del nombre de un producto o de una cadena de versión cuando el entorno de ejecución proporcione un mapa de capacidades. Los cambios revertidos repetidamente demuestran que la ruta de sondeo y alternativa forma parte del contrato. Cuando el comportamiento del paquete público dependa de un indicador de función, pero el paquete no pueda importar el registro privado, llame al gancho de extensión establecido con la cadena de clave exacta del indicador. Verifique la clave en el registro y pruebe tanto la ruta habilitada como la deshabilitada. No integre la lógica del registro privado en el paquete público. ## Ejecutar las pruebas, el lint y la compilación que el paquete tiene de verdad Defina el estado «correcto» a partir de los scripts que el paquete proporciona realmente. En un paquete solo de JavaScript, puede significar ejecutar el conjunto completo de pruebas y el linter, sin inventar un paso de comprobación de tipos que no existe. Ejecute la compilación cuando el cambio afecte a la salida de ejecución empaquetada. Registre cada archivo de prueba nuevo en el importador central del conjunto cuando la detección no sea automática; un archivo de prueba sin registrar no proporciona protección. Use el filtro de nombres de pruebas compatible para acotar la investigación, pero ejecute todo el conjunto obligatorio antes de terminar. Trate con cuidado los comandos de lint que aplican correcciones automáticas y revise su diff. Confirme que las pruebas, el lint y la compilación correspondiente del artefacto empaquetado se completen correctamente, y conserve las advertencias que revelen problemas de ejecución o compatibilidad. ## Confirmar todo el impacto antes de dar el cambio por terminado Empiece por el contrato afectado, no por el archivo más cercano. Busque los problemas conocidos y las dependencias descendentes, realice el cambio compatible más pequeño y verifique la seguridad de la publicación antes de informar que el trabajo ha terminado. La revisión final debe confirmar: - que ningún secreto, material restringido o contenido exclusivo para uso interno haya entrado en el paquete público; - que se mantengan los contratos de devolución de llamada, ganchos, importaciones profundas y orden del middleware; - que las migraciones sean aditivas e idempotentes; - que se hayan probado los límites de modelos, referencias, máquinas virtuales y capacidades de bases de datos cuando se vean afectados; - que las pruebas nuevas estén registradas y se superen los controles de calidad reales del paquete; - que los llamadores entre paquetes y la documentación se hayan actualizado donde corresponda; - que cualquier cambio incompatible o de versión principal se haya coordinado con todos los destinos de publicación. No considere que un cambio está aislado solo porque el número de dependencias del espacio de trabajo sea pequeño; los consumidores públicos siguen formando parte del modelo de riesgo.