Cambiar una biblioteca o SDK compartido sin romper su API pública

## Ejecutar todas las pruebas y compilaciones antes de dar un cambio por terminado Ejecuta la pila de verificación completa del proyecto antes de declarar completo cualquier cambio que afecte al código en tiempo de ejecución, a las pruebas o al comportamiento de compilación/pruebas. La verificación se aplica cuando modificas: - El código base de la biblioteca o utilidades compartidas. - Pruebas, incluidas las pruebas de instantáneas (snapshot). - Proyectos de ejemplo. - Configuración de compilación o de pruebas (manifiestos de dependencias, archivos del ejecutor de tareas, configuración de compilación de la documentación, flujos de trabajo de CI). Puedes omitir la verificación completa para cambios que afecten únicamente a la documentación o a metadatos del repositorio (documentación, guías para colaboradores, archivos de metadatos), salvo que el usuario solicite explícitamente la pila completa. Decide si aplica la verificación en función de los archivos realmente modificados, no de una percepción subjetiva de cuán grande es el cambio. Vuelve a ejecutar toda la pila después de aplicar cualquier corrección: una reejecución parcial oculta regresiones introducidas por la propia corrección. Al integrar con la API de una plataforma externa, consulta la documentación oficial de esa plataforma en lugar de basarte en suposiciones genéricas sobre APIs, e inspecciona la ruta de código local para entender el comportamiento propio de la biblioteca. ## No cambiar de rama ni de worktree de Git sin permiso del usuario Trabaja por defecto en el checkout actual del usuario y en la rama actual. Si la tarea ya se está ejecutando dentro de un worktree seleccionado, usa ese worktree sin solicitar permiso adicional. No crees ni cambies a otro worktree, y no crees ni cambies de rama, a menos que el usuario lo solicite o apruebe explícitamente esa acción exacta en la conversación actual. Una solicitud de implementar, investigar, revisar, probar o verificar cambios no autoriza por sí sola cambiar el worktree o la rama activa. Si realmente se necesita aislamiento o un checkout diferente, explica por qué y pide confirmación antes de cambiar cualquier estado de Git. Esto se cumple incluso cuando otra regla o flujo de trabajo recomiende un worktree enlazado: detente y solicita aprobación en lugar de seleccionar o crear uno automáticamente. ## Añadir los nuevos parámetros de la API al final para no romper las llamadas actuales El orden de parámetros y campos de las APIs públicas exportadas en tiempo de ejecución es un contrato, no un detalle de implementación. - Preserva el significado posicional de los argumentos existentes en constructores públicos y de los campos de dataclasses. Nunca insertes un nuevo parámetro o campo en medio del orden público existente. - Añade los nuevos campos o parámetros públicos opcionales al final, manteniendo los campos existentes en su orden original. - Si reordenar es inevitable, añade una capa de compatibilidad explícita más pruebas de regresión que ejerciten el patrón de llamada posicional antiguo. - Prefiere los argumentos con nombre (keyword arguments) en los puntos de llamada para reducir roturas accidentales, pero nunca te apoyes en eso para justificar la ruptura de la compatibilidad posicional. - Trata las rutas de importación previstas y las listas de exportación pública como contratos. Al añadir o mover un símbolo público, actualiza el módulo propietario, las reexportaciones previstas a nivel superior o de subpaquete, y una prueba de regresión de importación. - Mantén las importaciones de nivel superior libres de fallos por dependencias opcionales y de efectos secundarios en tiempo de ejecución; usa exportaciones diferidas (lazy) cuando sea necesario. ## Juzgar la compatibilidad según la última versión publicada y planificar el trabajo grande Evalúa los cambios disruptivos (breaking changes) contra la última versión publicada, no contra cambios acumulados en ramas locales aún no publicadas. Las interfaces introducidas o modificadas después de la última versión publicada pueden reescribirse directamente, sin capas de compatibilidad, salvo que definan un límite de estado externo duradero publicado o explícitamente soportado, o que el usuario solicite explícitamente una ruta de migración. Los formatos persistidos aún no publicados pueden renumerarse o consolidarse antes del lanzamiento cuando las instantáneas intermedias no están soportadas intencionalmente. Prefiere el reemplazo directo sobre las capas de compatibilidad para los cambios acumulados en ramas posteriores a una publicación. Señala el riesgo de compatibilidad de forma temprana — pero solo cuando el cambio afecte a un comportamiento incluido en la última versión publicada o a un límite de estado duradero publicado y soportado — y confirma el enfoque antes de implementar. Usa un plan de ejecución cuando el trabajo tenga varios pasos, abarque varios archivos, implique nuevas funcionalidades o refactorizaciones, o probablemente lleve más de una hora aproximadamente. Mantén actualizadas sus secciones vivas (progreso, hallazgos, registro de decisiones, resultados) a medida que ejecutas, y reescribe el plan si cambia el alcance. Si omites intencionalmente un plan para una tarea compleja, indica el motivo para que los revisores entiendan la decisión. ## Leer primero la referencia del subsistema y actualizar cada parte que alcanza el cambio El tiempo de ejecución de una biblioteca es un conjunto de subsistemas que interactúan entre sí: el bucle de ejecución (run loop), la ejecución de herramientas, los adaptadores de modelos y proveedores, el trazado (tracing), las sesiones y la persistencia, las canalizaciones en tiempo real y de voz, el sandboxing y el estado de ejecución serializado. Antes de modificar uno de ellos, lee su referencia de arquitectura dedicada y confirma que entiendes el límite que estás tocando. Cuando añadas o cambies una variante que se propaga por todo el sistema — un nuevo tipo de salida de modelo, llamada a herramienta, aprobación o elemento de ejecución — actualiza todas las superficies aplicables: procesamiento, eventos, repetición (replay), persistencia, trazado y serialización. Omitir una sola superficie produce corrupciones sutiles y difíciles de rastrear. Mantén alineados en su comportamiento los caminos de streaming y de no streaming. Para cualquier subsistema que posea conexiones, tareas u otros recursos, verifica la propiedad de los recursos tanto en el camino normal como en el de fallo. Cuando cambie la forma de un estado de ejecución serializado, sigue las reglas de límite de publicación, versión de esquema, lectura retroactiva (backward-read) y pruebas de regresión correspondientes a ese formato. ## Mantener la documentación fiel al código real y sacar los datos sensibles de los registros - La documentación suele publicarse en un sitio en vivo, así que coordina con cuidado los cambios de comportamiento y la documentación. Si la documentación describiría un comportamiento que aún no se ha publicado, retrasa el cambio de documentación hasta que la versión esté disponible, o divídelo en un seguimiento posterior. - Trata los fragmentos de documentación ejecutables como verificaciones de compatibilidad de la API. Antes de añadir ejemplos de constructores o de la API, verifica los argumentos mostrados y la forma de la llamada contra la implementación real. - No permitas que datos de sandbox o de manifiesto no confiables se excluyan a sí mismos de los límites del sistema de archivos del host o del directorio base. Las vías de escape para la materialización local deben estar controladas por código de aplicación confiable en el punto de llamada, nunca por datos de manifiesto serializados. - Al documentar una concesión o un límite de seguridad, verifica que la ruta de código real la haga cumplir. No afirmes que una concesión se aplica a una ruta de materialización (directorio local, archivo local, extracción de archivo comprimido) a menos que esa ruta realmente la consulte. - Al redactar (censurar) cargas útiles sensibles, ten en cuenta la visualización de trazas (traceback), el encadenamiento de excepciones, el contexto de excepción retenido, los registros (logs) y la telemetría. Suprimir una traza no es suficiente si el objeto de excepción original todavía conserva la entrada sensible. ## Pasar las comprobaciones de formato y pruebas, y preparar la entrega del PR Amplía las pruebas cada vez que toques código, y asegúrate de que las comprobaciones relevantes pasen antes de enviar el cambio. - Ejecuta la suite de pruebas completa; usa ejecuciones de pruebas focalizadas por patrón mientras iteras. - Ejecuta la verificación estática de tipos; las anotaciones de tipo deben pasar. - Para las pruebas basadas en instantáneas (snapshot), regenera las instantáneas deliberadamente y vuelve a ejecutar la suite después. - La cobertura debe mantenerse por encima del umbral del proyecto. - Aplica el formateador y el linter; mantén las importaciones ordenadas; escribe los comentarios como oraciones completas que terminen en punto. - Ejecuta las comprobaciones en el orden obligatorio del proyecto: primero formato, luego linter, luego verificación de tipos, luego pruebas. Para pull requests y commits: - Usa la plantilla de PR del proyecto: incluye un resumen, un plan de pruebas y el issue relacionado cuando corresponda. - Escribe mensajes de commit concisos en modo imperativo; mantén los commits pequeños y enfocados. - Añade pruebas para el nuevo comportamiento y actualiza la documentación para cualquier cambio visible para el usuario. - Antes de tu respuesta final para un cambio elegible, produce un bloque de entrega de PR (resumen, nombre de rama sugerido, título, descripción en borrador). Producir esta entrega no autoriza por sí sola crear una rama, hacer commit, hacer push o abrir un pull request; omítelo solo para tareas triviales o meramente conversacionales, tareas meta o de documentación sin impacto en el comportamiento, o cuando el usuario indique que no lo incluyas. Los revisores buscan: comprobaciones que pasen; pruebas que cubran el nuevo comportamiento y los casos límite; código legible y coherente; cambios documentados en la API pública y de cara al usuario; ejemplos actualizados cuando cambia el comportamiento; y un historial limpio con una descripción clara.