Cambia un monorepositorio de automatización multilenguaje sin romper la compatibilidad

## Lee las reglas del repositorio y luego las instrucciones más cercanas a los archivos que cambias Empieza por las reglas del repositorio y, después, lee las instrucciones más cercanas a los archivos que vas a modificar. Los bindings de lenguaje, la infraestructura compartida, los componentes nativos y las herramientas de publicación pueden definir restricciones más específicas. Si el repositorio proporciona un área local ignorada por el control de versiones para preferencias de colaboradores, artefactos generados, trabajo provisional o resultados de compilación aislados, revisa la capa de instrucciones documentada para esa área antes de empezar. Trata las instrucciones locales definidas por el usuario como contexto adicional dentro de la tarea actual y de las reglas de seguridad de nivel superior. Organiza el repositorio por responsabilidades: - los bindings de lenguaje son responsables de las API, las pruebas y el estilo específicos de cada lenguaje; - las áreas compartidas de protocolo, transporte, compilación, fixtures y scripts afectan a varios consumidores; - los administradores nativos, los servicios de grid o enrutamiento y las definiciones de dependencias tienen un radio de impacto elevado; - el código de terceros es de solo lectura, salvo que la tarea requiera explícitamente mantenerlo; - los resultados generados nunca deben editarse manualmente. No des por sentado que la documentación para usuarios finales, las guías para colaboradores y las referencias de API generadas se encuentran en el mismo lugar. ## Mantén compatibles las API públicas y haz cambios pequeños que se puedan deshacer Mantén la compatibilidad de la API pública y la compatibilidad binaria, salvo que la tarea autorice explícitamente una ruptura. Normalmente, los usuarios deberían poder actualizar cambiando únicamente la versión. Evita las refactorizaciones de todo el repositorio, los formateos masivos y la limpieza no relacionada. Prefiere un cambio pequeño y reversible que resuelva un único problema. Antes de eliminar un comportamiento público, márcalo como obsoleto y ofrece una alternativa de migración clara. No interpretes la ausencia de versionado semántico como permiso para retirar funcionalidades sin un periodo de transición. Prefiere mover o copiar los archivos bajo control de versiones en lugar de eliminarlos y volver a crearlos cuando así se conserve su historial. Solicita una verificación antes de modificar áreas de alto riesgo, salvo que el usuario ya haya indicado el cambio. Entre estas áreas se incluyen la semántica de protocolos compartidos, la serialización en el protocolo de comunicación, el análisis de capacidades, el reajuste de versiones fijadas de dependencias, los fixtures de pruebas compartidos, la configuración de compilación, el enrutamiento, las colas de distribución y el código utilizado por varios bindings. ## Compila solo el target afectado más pequeño con la herramienta de compilación fijada Utiliza el punto de entrada de compilación hermético y fijado por el repositorio, en vez de suponer que existe un entorno local configurado para un lenguaje concreto. Explora el grafo de compilación antes de leer grandes partes del árbol. Consulta las etiquetas y dependencias de los targets y, después, compila o prueba el target más pequeño que cubra el cambio. Intenta ejecutar directamente el comando de compilación canónico. Si las restricciones del sandbox, la red o la cadena de herramientas impiden ejecutarlo, informa del bloqueo y proporciona el comando exacto que el usuario puede ejecutar por separado. Cuando el directorio de salida predeterminado esté restringido o se utilice un árbol de trabajo secundario, aísla los resultados de compilación: - coloca la opción de inicio `output-base` antes del comando `build`, `test` o `query`; - fija la ruta a la raíz del repositorio para que se resuelva de forma coherente desde cualquier directorio; - guarda los resultados aislados dentro del área local ignorada por el control de versiones. No ejecutes purgas destructivas de caché como medida rutinaria de resolución de problemas. Prefiere recompilaciones específicas y explica cualquier invalidación de caché que sea realmente necesaria. ## Comprueba que los bindings de otros lenguajes se comporten igual Cuando cambie un comportamiento visible para el usuario, compara la implementación con al menos otro binding de lenguaje. Comprueba la paridad especialmente en: - nombres de métodos públicos, argumentos, valores predeterminados y comportamiento de retorno; - comandos de protocolo y serialización; - transporte remoto y asignación de errores; - análisis de capacidades y opciones; - elementos obsoletos y rutas de migración; - ejemplos de documentación y registros destinados al usuario. Para comportamientos compartidos de bajo nivel, identifica todos los bindings o servicios que puedan consumir el cambio. Si la tarea actual no permite actualizarlos todos de forma segura, informa del trabajo posterior necesario para restablecer la paridad o recomienda crear una incidencia para darle seguimiento. No impongas una estructura interna idéntica en todos los lenguajes. Conserva el comportamiento compartido respetando las convenciones establecidas de cada binding y sus prácticas de pruebas. ## Empieza con una prueba pequeña que falle y usa piezas reales en lugar de mocks Prefiere escribir una prueba que falle antes de implementar el cambio de comportamiento. Empieza con una prueba unitaria o de contrato pequeña; usa pruebas de navegador o de extremo a extremo únicamente cuando el comportamiento no pueda verificarse de forma fiable en un nivel inferior. Evita los mocks cuando puedan representar de forma incorrecta un protocolo público o el contrato de un binding. Prefiere analizadores y serializadores reales, fixtures locales, servidores ligeros o entornos de integración existentes. Utiliza el grafo de compilación para seleccionar el target de prueba relevante más específico. Entre los controles útiles se incluyen: - filtrar para ejecutar pruebas pequeñas; - mostrar la salida completa de las pruebas durante la depuración; - desactivar los resultados de pruebas almacenados en caché cuando sea necesaria una nueva ejecución real; - consultar las instrucciones específicas del lenguaje para conocer el target y las opciones correctos. Verifica que las pruebas esperadas se hayan ejecutado realmente. Que la herramienta de compilación termine correctamente sin ninguna prueba coincidente no demuestra que el resultado sea correcto. Después de que pase la prueba específica, amplía la comprobación únicamente al binding, al target compartido o a la superficie de integración directamente afectados. ## Escribe registros y comentarios útiles y formatea solo lo que cambió Añade registros cuando los usuarios u operadores necesiten visibilidad sobre estados importantes, reintentos, enrutamiento o causas de fallos. Sigue las convenciones de registro específicas del lenguaje y evita mensajes ruidosos que dupliquen diagnósticos de niveles inferiores. Escribe comentarios para explicar por qué existe una restricción o solución provisional, no para describir lo que ya expresa un código con nombres claros. Utiliza el formateador canónico del repositorio. Si un hook `pre-commit` o `pre-push` ya ejecuta el formateo necesario para el ámbito relevante, deja que se encargue de ello en vez de repetir el formateo. Cuando ningún hook cubra el cambio, ejecuta el modo más específico del formateador que se ajuste a la entrega prevista. No formatees todo el repositorio porque haya cambiado un solo archivo. Mantén cada cambio propuesto centrado en un único propósito para que la revisión, la reversión y el impacto entre bindings sigan siendo comprensibles. ## Confirma que la compilación y las pruebas se ejecutaron e informa de lo que no pudo ejecutarse Antes de terminar: 1. confirma que el target modificado se compila con la cadena de herramientas hermética; 2. ejecuta las pruebas específicas y verifica que hayan ejercitado el comportamiento previsto; 3. ejecuta la comprobación de formato o lint pertinente; 4. revisa el diff para detectar cambios no relacionados y resultados generados; 5. examina las implicaciones para la compatibilidad y la obsolescencia; 6. compara al menos otro binding cuando haya cambios visibles para el usuario; 7. identifica todas las áreas compartidas de alto riesgo que se hayan tocado. Informa de qué se modificó, qué targets y pruebas se ejecutaron realmente, qué no pudo ejecutarse y por qué. Señala los archivos de alto riesgo, el comportamiento compartido, el impacto entre bindings y cualquier trabajo posterior. No afirmes que existe una compatibilidad amplia basándote en la prueba de un único binding. No declares que el trabajo está terminado si la cadena de herramientas hermética no estaba disponible sin indicar claramente que la verificación quedó incompleta.