“Funciona aquí” no es un build gate

1218. Identidad de la lección

Módulo

3.10 — Pipeline de build

Lección

1 — “Funciona aquí” no es un build gate

Tipo académico

Concepto

Tipo de esquema

texto

Orden

1

Tiempo estimado

30–45 minutos

Esta lección define la evidencia mínima necesaria para aceptar un build. El foco no está en un comando concreto del motor ni en un servicio específico. El objetivo es formular una afirmación que otra persona pueda inspeccionar, incluida la referencia conocida de Git —un commit o un tag— que identifica el estado del repositorio.

1219. Objetivo de aprendizaje

Al terminar esta lección, podrás especificar un conjunto mínimo de evidencias y un gate de aceptación para un build. Para ello, identificarás sus entradas, el artefacto, el entorno de ejecución, la referencia de Git y las comprobaciones observables, y distinguirás la evidencia de aceptación de la evidencia de reproducibilidad.

1220. Por qué importa

Que un build se ejecute en una máquina no demuestra que sea reproducible. Puede depender de un asset no registrado, una configuración local o una diferencia de entorno. Esto dificulta reproducir los fallos y reduce la confianza en un resultado positivo. Un commit o tag conocido vincula la evidencia con un estado concreto del repositorio, en lugar de hacerlo con un directorio de trabajo sin identificar. La IA puede ayudar a proponer comandos, configuraciones o hipótesis de fallo, pero no sustituye una definición precisa de lo que cuenta como evidencia. Un build gate convierte “me funcionó” en una afirmación con condiciones que se pueden inspeccionar.

1221. Conocimientos previos

Debes poder auditar un conjunto de assets mediante un manifest, identificar la función prevista de cada asset y distinguir entre que un asset esté presente y que sea adecuado para su uso. Esta lección se apoya en el módulo 3.9, Auditar un conjunto de assets. También debes poder identificar la revisión del repositorio utilizada para un trabajo controlado.

1222. Concepto central

La reproducibilidad y la evidencia de aceptación están relacionadas, pero no son el mismo modelo. La reproducibilidad indica si otra persona podría recrear o volver a ejecutar un resultado a partir de factores suficientemente identificados. Entre esos factores se encuentran el estado del código fuente, las entradas del proyecto y sus assets, las dependencias, las versiones de las herramientas, la configuración, el procedimiento de build y el entorno de ejecución relevante.

Usa I-A-E-G para organizar la afirmación de aceptación y sus evidencias:

1. Entradas — el material utilizado para producir el build: archivos del proyecto, código, assets, configuración, dependencias e información de versiones relevante.
2. Artefacto — la salida producida que se va a evaluar, como un paquete del juego u otra salida definida de forma explícita.
3. Entorno — las condiciones en las que se crea o ejecuta el artefacto: sistema operativo, versión del motor o de las herramientas, runtime necesario, supuestos de hardware y ajustes que afecten al resultado.
4. Gate — los criterios observables que determinan si el artefacto se acepta, se rechaza o requiere investigación.

Una referencia de Git identifica el estado del repositorio asociado con las entradas y el artefacto, pero no es una categoría adicional de I-A-E-G ni demuestra por sí sola la reproducibilidad. El registro de dependencias, las versiones de las herramientas, la configuración, el procedimiento de build y la evidencia del entorno aportan los demás factores necesarios para evaluar la reproducibilidad.

I-A-E-G permite explicar qué se evalúa y qué resultado se acepta. Las entradas responden “¿a partir de qué?”; el artefacto, “¿qué se produjo?”; el entorno, “¿en qué condiciones?”; y el gate, “¿qué debe observarse?”. Mantener estas funciones separadas evita confundir un gate aprobado con la prueba de que el build puede reproducirse en otro entorno.

Un build gate debe ser lo bastante concreto para poder comprobarse y lo bastante relevante para proteger la siguiente etapa del trabajo. “El proyecto se abre” puede servir como comprobación inicial, pero no demuestra por sí solo que se haya producido el build previsto ni que esté disponible su comportamiento crítico.

1223. Modelo mental

Usa dos perspectivas relacionadas: los factores de reproducibilidad y el modelo I-A-E-G de aceptación y evidencia. I-A-E-G organiza la afirmación de aceptación; los factores de reproducibilidad indican si otra persona podría recrear o repetir el resultado. La referencia de Git vincula las entradas declaradas con un estado del repositorio, pero no sustituye ninguna de las dos perspectivas.

La evidencia de aceptación debe formar una cadena I-A-E-G trazable:

Entradas → Artefacto → Entorno → Resultado del gate

La evidencia de reproducibilidad atraviesa esa cadena y registra la revisión del código fuente, las dependencias, las versiones de las herramientas, la configuración, el procedimiento de build y las demás condiciones necesarias para recrear o repetir el resultado. Un commit o tag conocido forma parte de la identidad del build, pero no demuestra por sí solo que el artefacto proceda de esa revisión ni que el proceso sea reproducible.

Cuando una ruta o un nombre de archivo pueda sobrescribirse, es recomendable —aunque no obligatorio— registrar un identificador inmutable del artefacto. Un checksum, un ID inmutable o un nombre de archivo con una versión única ayuda a identificar los bytes exactos que se evaluaron. Sin embargo, ese identificador no demuestra por sí solo que el artefacto se haya generado desde la revisión o mediante el procedimiento declarados. La evidencia todavía debe vincularlo con las entradas, el entorno y las comprobaciones.

Si falta un elemento de aceptación o un factor de reproducibilidad, limita la afirmación en consecuencia. Por ejemplo, “el artefacto se inicia en esta máquina” es una observación de ejecución limitada, no una prueba de que el proceso de build sea reproducible.

1224. Ejemplo concreto

Imagina que un equipo produce un paquete jugable para una pequeña parte de un juego. Una persona lo inicia en su ordenador de desarrollo y afirma: “Funciona aquí”. Esa frase deja varias preguntas sin responder:

• ¿Qué entradas de código y assets produjeron el paquete?
• ¿Es el paquete previsto o una salida local anterior?
• ¿Qué commit o tag de Git identifica el estado del repositorio?
• ¿Qué versiones de las herramientas y del runtime se utilizaron?
• ¿Qué configuración y procedimiento de build se siguieron?
• ¿Se probó el artefacto en un entorno limpio o en otro entorno descrito explícitamente?
• ¿Qué comportamiento se comprobó después del inicio?

Un gate mínimo más sólido podría exigir lo siguiente:

• identificar el conjunto de entradas y registrar el commit o tag conocido asociado;
• nombrar el artefacto de salida e indicar dónde se produjo;
• registrar, de forma opcional, un checksum, un ID inmutable o un nombre de archivo con una versión única para identificar los bytes evaluados;
• registrar las herramientas, la configuración, el procedimiento y el entorno de runtime relevantes;
• iniciar el artefacto desde la salida declarada;
• comprobar que aparece el punto de entrada esperado;
• recorrer un camino crítico definido y registrar si se supera o falla;
• conservar evidencia suficiente para que otra persona pueda repetir la comprobación.

Por ejemplo, una nota de evidencia podría identificar build-slice-a-01.zip, su checksum, el manifest de assets declarado y una referencia hipotética como commit abc1234 o tag build-slice-a-01. La referencia solo es significativa si corresponde a la revisión elegida para este build hipotético. El checksum identifica el archivo evaluado, pero ninguno de esos valores establece por sí solo la procedencia completa del build.

Esto no afirma que se hayan detectado todos los defectos posibles. Solo afirma que se cumplieron las condiciones y comprobaciones declaradas para el estado del repositorio y el artefacto identificados.

1225. Error común

El error habitual es tratar un inicio local satisfactorio como prueba de reproducibilidad. Un inicio local puede servir como evidencia para un gate concreto, pero no identifica las entradas, no distingue el artefacto de otras salidas locales, no establece el entorno, no documenta el procedimiento de build ni vincula el resultado con un estado conocido de Git.

Otro error consiste en registrar una rama como main sin indicar un commit o tag. Una rama puede avanzar; la evidencia debe identificar el estado concreto que se está evaluando. Una ruta o un nombre genérico de archivo también puede sobrescribirse, por lo que conviene utilizar un identificador inmutable cuando importe la identidad exacta del artefacto. Recuerda que identificar el artefacto no demuestra su procedencia.

También es un error formular un gate tan amplio que no pueda comprobarse, por ejemplo: “el juego funciona correctamente”. Sustituye las afirmaciones generales por comprobaciones observables relacionadas con el propósito del build.

1226. Práctica guiada

Crea una especificación mínima de evidencia para el build de una parte hipotética de un juego. No generes un build ni modifiques un proyecto. Toma primero esta decisión: ¿Qué único comportamiento es lo bastante importante para formar parte del gate mínimo de aceptación y qué comportamientos quedan explícitamente fuera de ese gate?

Después, completa esta tabla:

Revisa la especificación con estas preguntas:

1. ¿Puede otra persona identificar el artefacto exacto que se evaluará?
2. Si has utilizado un checksum o un ID de artefacto, ¿has evitado presentarlo como prueba de la procedencia del build?
3. ¿El artefacto está vinculado con un commit o tag conocido, en lugar de depender solo de una rama cambiante o una carpeta local?
4. ¿Puede otra persona distinguir las entradas declaradas de una dependencia local accidental?
5. ¿La descripción del entorno y del procedimiento incluye las condiciones que podrían cambiar el resultado?
6. ¿Cada comprobación puede registrarse como superada o fallida sin depender de la confianza o de afirmaciones indirectas?
7. ¿El gate protege el propósito de este build sin pretender validar el juego completo?

1227. Validación / evidencia

1228. Puntos clave

• I-A-E-G organiza la afirmación de aceptación en entradas, artefacto, entorno y gate.
• La reproducibilidad depende de identificar con suficiente precisión el estado del código fuente, las dependencias, las versiones de las herramientas, la configuración, el procedimiento de build y el entorno relevante; no equivale a superar un gate de aceptación.
• Un commit o tag conocido identifica el estado del repositorio, pero no es una quinta categoría de I-A-E-G ni demuestra por sí solo la reproducibilidad.
• Un checksum, un ID inmutable o un nombre de archivo con una versión única puede identificar el artefacto evaluado, pero no demuestra su procedencia.
• Un inicio local aporta evidencia de una comprobación limitada, no una prueba automática de que el build sea reproducible.
• Un build gate debe indicar qué se comprueba, cómo se observa y qué queda fuera de su alcance.

1229. Siguiente lección

A continuación, continúa con 3.10 L2 — Definir un gate de clean build para redactar y ejecutar un checklist de clean build y registrar si el artefacto declarado y las comprobaciones de aceptación producen el resultado observable esperado.

1230. Comprobación