Poniendo al día al SDK antes de que pudiera desviarse

La paridad construida al inicio de un proyecto cuesta mil veces menos que la paridad añadida después de que el proyecto ya se lanzó. Los bindings de RakuAI se codesarrollan con el runtime, controlados en cada PR, de modo que tu elección de binding nunca te deje sin acceso a una función más adelante.

Ya nervioso por un modo de fallo específico que he visto matar proyectos multirrepositorio antes, y ese era el estado de partida de la mañana del sábado. El runtime añade una función un fin de semana y el SDK no se pone al día hasta el mes siguiente. Los ejemplos en un binding funcionan y los ejemplos en el otro binding retroceden silenciosamente. Los números de versión dejan de coincidir. El CI de cada repositorio está en verde y la integración entre ellos está rota.

Esa película termina en una replataformización dos años después. No estoy construyendo Raku de esa manera. El plan para este fin de semana era poner al SDK al día con el runtime antes de que la brecha pudiera formarse, y dejar atrás suficiente infraestructura para que la brecha nunca pueda formarse de nuevo.

Lo que aterrizó en el lado del SDK

El SDK tuvo un gran fin de semana. El lado del runtime estuvo más tranquilo (la mayor parte de su gran empujón ocurrió el fin de semana anterior con el PR #104 que hizo aterrizar VIO/SLAM, el Programador de QoS, el Arnés de Rendimiento y el pipeline de telemetría). Este fue el fin de semana de ponerse al día para los bindings.

Aspectos destacados:

• Paridad SDK v0.2.0 entre Unity y Unreal, con validación exhaustiva
• Ejemplos HelloAR en ambos bindings, con demostraciones explícitas de failover
• Interacciones mejoradas del ejemplo de Unity con soporte multiobjeto y tutoriales interactivos
• Documentación de API de Unreal mejorada con ejemplos de uso exhaustivos
• Flujo de trabajo Agent-Queue Seeder portado al repositorio del SDK
• Pipeline de CI/CD para la publicación del paquete SDK v0.2 con versionado semántico y automatización de lanzamientos
• Documentación y guía rápida del SDK v0.2 con página de inicio del repositorio e integración con la wiki
• Epic #42: infraestructura de pruebas de paridad entre SDK y Runtime completada

El trabajo del Epic #42 es el titular. Es una suite de pruebas que ejercita ambos bindings contra los mismos escenarios canónicos y confirma que se comportan igual. Unity HelloAR y Unreal HelloAR cada uno carga un modelo, lo ancla a un marcador, lo renderiza, y reporta telemetría. La prueba de paridad confirma que la telemetría que reportan ambos bindings está dentro de tolerancia, y que el mismo modelo se carga correctamente en ambos. Si un cambio en el runtime alguna vez rompe un binding sin romper el otro, la prueba de paridad lo detecta.

Por qué importan las pruebas de paridad en esta etapa

El SDK de Raku todavía no se lanza. No hay una versión pública. Faltan meses para que alguien fuera del equipo escriba código contra esto. Entonces, ¿por qué preocuparse por la paridad ahora?

Porque las pruebas de paridad construidas al inicio de un proyecto cuestan mil veces menos que las pruebas de paridad añadidas a un proyecto que ya se lanzó. Cada nueva API en C que el runtime añade se ejercita a través de ambos bindings desde el primer día. Cada PR que toca la superficie pública tiene que demostrar que la prueba de paridad todavía pasa, o explicar por qué no. El costo es unos minutos por PR. El ahorro son meses de triaje posteriores cuando un socio reporta un problema que solo se reproduce en Unreal y el equipo tiene que averiguar por qué.

La otra razón es que las pruebas de paridad sacan a la superficie problemas arquitectónicos. Cuando una función es fácil de exponer en Unity y difícil en Unreal, el problema usualmente no está en los bindings. Está en la API en C del runtime. La asimetría es una señal. Este fin de semana las pruebas de paridad sacaron a la superficie dos asimetrías de este tipo, y la solución en ambos casos fue cambiar la superficie de API del runtime en lugar de trabajar alrededor de la asimetría en uno de los bindings.

Cómo funciona el flujo de trabajo de dos corrientes

El patrón al que he llegado para el desarrollo multirrepositorio con agentes:

Una cola de agentes por repositorio. El runtime tiene su propia cola de issues, el SDK tiene su propia cola de issues, la documentación tiene la suya. Cada agente trabaja dentro de su repositorio. Ningún agente intenta abarcar la costura entre dos repositorios en un solo PR.

Coordinación entre repositorios a nivel de issue. Cuando una función requiere cambios en ambos repositorios, se presentan dos issues acoplados al mismo tiempo, con referencias cruzadas. El PR del runtime aterriza primero. El PR del SDK se retiene hasta que se hace merge del PR del runtime. Luego el PR del SDK se actualiza contra el nuevo build del runtime, se vuelve a probar, y se hace merge en cuestión de horas.

Un conjunto de ejemplos canónico en cada binding. Unity HelloAR y Unreal HelloAR son los vehículos de prueba canónicos. Cada cambio en la API en C tiene que ejercitarse en ambos. Los ejemplos no son un añadido posterior. Son parte de la superficie pública.

Pruebas de paridad como puerta de CI. La infraestructura de pruebas de paridad que aterrizó este fin de semana como Epic #42 ahora se ejecuta en cada PR que toca cualquiera de los dos repositorios. Si un cambio en el runtime no ejercita ambos bindings, el PR queda bloqueado para hacer merge hasta que la prueba de paridad demuestre que el cambio funciona en ambos lados.

Lo que esto habilita para los constructores

Si eres un desarrollador de Unity pensando en construir sobre Raku eventualmente, el binding se está codesarrollando con el runtime, no persiguiéndolo después. La API de Unity no se quedará atrás. Los ejemplos funcionarán hoy y funcionarán en la versión 1.0.

Si eres un desarrollador de Unreal, lo mismo es cierto. El binding de Unreal tiene prioridad idéntica al de Unity. Las pruebas de paridad lo demuestran.

Si estás decidiendo con qué binding empezar, la respuesta es el que se ajuste a las habilidades existentes de tu equipo. Las pruebas de paridad son lo que me permite prometer que la elección de binding no te dejará sin acceso a funciones más adelante.

Si eres un socio pensando en cómo este motor se integra en tu stack, la superficie va a ser API en C más binding de Unity más binding de Unreal más eventualmente algunos más (Godot está en la hoja de ruta, web-nativo está en la hoja de ruta). Cada nuevo binding tiene que hacer aterrizar sus propias pruebas de paridad contra el conjunto canónico antes de lanzarse. La disciplina viene incorporada.

Honesto sobre lo que sigue siendo tosco

Las pruebas de paridad cubren lo básico. El anclaje basado en marcadores funciona en ambos bindings. HelloAR carga y renderiza en ambos. La telemetría reporta correctamente en ambos. Las preguntas de paridad más difíciles, seguimiento completo de manos, pipeline de voz, sincronización de pose multijugador, esas todavía no tienen pruebas de paridad porque el lado del runtime no está terminado. Vendrán bajo la misma puerta cuando lo esté.

El pipeline de CI para la publicación del SDK v0.2 está en pie, pero el paquete publicado real todavía no es lo bastante estable como para recomendar integrarse contra él. Trata el SDK como en desarrollo durante todo octubre. Para noviembre las pruebas de paridad serán lo bastante profundas como para que la recomendación sea distinta.

Lo que quiero recordar de este fin de semana

Dos cosas.

La paridad multirrepositorio es una disciplina, no una función. El fin de semana en que el SDK se puso al día con el runtime es un fin de semana sin ninguna función nueva y brillante en el runtime. No pasó nada demostrable. Lo que pasó fue que el SDK dejó de quedarse atrás. Ese es el tipo de trabajo que, si se descuida, mata un proyecto multirrepositorio. Quiero dejarlo escrito para no olvidarlo cuando llegue la próxima gran función del runtime.

La cola de agentes escala por repositorio. Correr una sola cola a través de ambos repositorios en el mismo flujo de trabajo produjo una versión temprana del desorden de conflictos de merge que describí el fin de semana pasado a nivel del runtime. Separar las colas por repositorio eliminó casi todo eso. Los agentes dejan de estorbarse entre sí cuando sus espacios de problema están correctamente delimitados.

Sábado por la noche, el SDK y el runtime están en paridad. Gran fin de semana. El tipo correcto de fin de semana.