Cambiar un envoltorio administrado y su biblioteca nativa sin romper la ABI

## Seguir cada cambio desde el envoltorio administrado hasta el código nativo Trata la biblioteca como un sistema por capas: envoltorio administrado, declaraciones de interoperabilidad, API estable compatible con C e implementación nativa. - Valida las entradas públicas en el envoltorio administrado. - Mantén el puente compatible con C pequeño y predecible; debe traducir y reenviar, no duplicar políticas. - Conserva una correspondencia exacta entre las declaraciones administradas, los símbolos C exportados, los tipos de parámetros, los tipos de retorno y las implementaciones nativas. - Antes de editar código, determina qué capa posee cada regla de validación, asignación, conversión de errores y transición de ciclo de vida. - Sigue un cambio a través de todas las capas afectadas en lugar de corregir solo el primer error de compilación. Un cambio que compila en la capa administrada todavía puede fallar en tiempo de ejecución si el binario nativo no contiene el símbolo nuevo o utiliza una firma diferente. ## Elegir binarios nativos precompilados o compilados desde la fuente según el cambio Los binarios nativos deben existir antes de compilar el envoltorio administrado, pero su origen correcto depende de qué se haya modificado. - Para trabajo exclusivamente administrado, usa los artefactos nativos precompilados que el repositorio aprueba para el hito publicado actual. - Para cambios en la implementación nativa, la API C, dependencias, submódulos, versiones o hitos, compila los binarios nativos desde el código fuente para la plataforma y arquitectura objetivo. - Después de cualquier cambio que afecte al lado nativo, queda prohibido descargar los binarios precompilados actuales hasta que esos cambios se hayan publicado en el origen de artefactos. - Si falla la compilación nativa desde el código fuente, diagnostica sus requisitos de herramientas, dependencias, rutas o red. Nunca recurras a descargas obsoletas solo para conseguir que pase la compilación administrada. - Limpia las cachés de plataforma cuando puedan conservar un módulo nativo anterior y producir resultados de prueba falsos. Usar binarios nativos obsoletos después de cambiar una API puede producir una compilación silenciosamente incorrecta y, más tarde, fallos por puntos de entrada ausentes en tiempo de ejecución. ## Regenerar los enlaces en vez de editarlos y mantener estable la ABI No edites manualmente enlaces generados, documentación generada, páginas de versión renderizadas ni ningún otro resultado declarado como generado. Modifica la fuente editable y ejecuta el generador del repositorio después de cualquier cambio en la API C. Mantén estable la interfaz binaria de aplicaciones: - Añade sobrecargas, métodos o tipos en lugar de cambiar firmas existentes. - No elimines API públicas ni cambies sus tipos de retorno. - Prefiere sobrecargas a nuevos parámetros predeterminados, porque estos pueden alterar la compatibilidad binaria. - Marca una API como obsoleta en lugar de eliminarla y proporciona instrucciones de migración aplicables. - Mantén las convenciones de nombres y parámetros coherentes con las API públicas circundantes. - Regenera los enlaces y revisa la diferencia resultante antes de compilar. Cuando la documentación tenga páginas generadas y fuentes auxiliares editables, modifica únicamente la fuente designada y vuelve a renderizar el resultado. ## Clasificar la propiedad de los punteros nativos y no compartir objetos mutables entre hilos Clasifica cada puntero nativo antes de escribir un envoltorio: - Un parámetro prestado no transfiere la propiedad. - Un objeto nativo con propiedad manual requiere la ruta de liberación nativa del envoltorio. - Un objeto con recuento de referencias debe usar el contrato de referencias del envoltorio. Ajusta el comportamiento ante fallos a cada capa. La API compatible con C devuelve un puntero nulo o `false`; una fábrica administrada devuelve `null`; un constructor administrado lanza una excepción cuando no puede establecer un objeto válido. Algunas operaciones nativas pueden devolver la misma instancia que recibieron. Compara las identidades antes de liberar el origen; de lo contrario, el valor devuelto podría hacer referencia a un objeto ya liberado. No compartas objetos nativos mutables entre hilos salvo que el contrato nativo lo permita expresamente. Proporciona a cada hilo su propio estado mutable; comparte solo objetos documentados como inmutables y seguros para hilos. Nunca pases a código nativo un puntero administrado fijado temporalmente si puede conservarlo después del ámbito de fijación. Usa un identificador fijado con ciclo de vida explícito o asigna memoria no administrada. Infringir esta regla permite que el recolector de basura mueva la memoria mientras el código nativo aún conserva la dirección anterior. ## Usar ramas de trabajo en el repositorio principal y en el submódulo nativo Crea una rama de función antes de realizar confirmaciones. Nunca confirmes cambios directamente en ramas protegidas. Aplica la misma regla de forma independiente a un submódulo nativo o repositorio anidado: tiene su propio estado de ramas, ramas protegidas, confirmaciones y ruta de revisión. 1. Crea una rama de función enfocada en el repositorio principal. 2. Si cambia el repositorio nativo anidado, crea allí su rama de función antes de editar o confirmar. 3. Mantén todas las confirmaciones en las ramas de función correspondientes. 4. Envía los cambios a revisión mediante el flujo de solicitudes de incorporación aprobado por el repositorio. 5. Confirma que el repositorio principal registra la revisión nativa prevista y ya revisada. No modifiques directorios nativos gestionados por el proyecto de origen fuera de la superficie de adaptación o extensión declarada por el repositorio. ## Probar con los binarios nativos correctos sin omitir fallos Una compilación correcta no constituye la finalización. Ejecuta las pruebas administradas pertinentes contra binarios nativos producidos mediante la ruta de bootstrap correcta. - Las pruebas deben pasar antes de afirmar que el trabajo está terminado. - No omitas una prueba fallida ni introduzcas una excepción de omisión para eludir una regresión. - Solo se admite una omisión ante una limitación demostrada de hardware o plataforma, como la ausencia de pantalla, un dispositivo gráfico no disponible o una función no compatible con la plataforma. - Regenera los enlaces antes de probar cuando haya cambiado la API C. - Limpia los artefactos nativos web o de plataforma almacenados en caché antes de validar cambios de versión. - Verifica plataformas y arquitecturas representativas para trabajos que afecten al lado nativo. Escribe pruebas que fallen cuando sean incorrectos la propiedad, el manejo de valores nulos, los símbolos exportados, la ABI, el ámbito de los hilos o la liberación. Incluye pruebas de paridad y mediciones de rendimiento para cambios de rendimiento cuando el comportamiento exacto o la mejora aún no estén demostrados. ## Encontrar errores entre capas por la forma del fallo Establece una línea base válida conocida, cambia una variable cada vez, registra cada resultado y trata las diferencias entre plataformas como evidencia. Si un cambio empeora el estado, reviértelo antes de probar otra hipótesis. Usa la forma del fallo para elegir el primer límite que debes inspeccionar: - La ausencia de un tipo administrado sugiere que los enlaces no se regeneraron o no se incluyeron. - Un símbolo nativo sin resolver sugiere que la declaración C y la implementación no coinciden. - Un punto de entrada ausente en tiempo de ejecución indica con fuerza binarios nativos obsoletos o una exportación no coincidente. - Una infracción de acceso sugiere corrupción de propiedad, liberación, fijación o firma. - Un fallo por referencia nula tras una llamada de fábrica sugiere que la capa nativa devolvió un fallo y el llamador lo ignoró. - Los cierres inesperados aleatorios entre hilos sugieren que se compartieron objetos nativos mutables. Antes de finalizar, inspecciona las diferencias generadas, compila el código nativo cuando sea necesario, compila el envoltorio administrado, ejecuta las pruebas y verifica la matriz de plataformas afectada. Informa del origen y la arquitectura exactos usados para el bootstrap. No afirmes que el trabajo tuvo éxito si las pruebas fallan, si las compilaciones nativas necesarias se sustituyeron por descargas o si la verificación de plataformas sigue incompleta.