Arquitectura del núcleo de BeeverForge

Principios del repositorio

Las reglas que se impone el repositorio del núcleo, desde cómo se nombra una prueba hasta cómo se publica una versión. La mayoría están escritas en CONTRIBUTING.md y docs/RELEASING.md y las hace cumplir una prueba o un workflow; cuando una regla es una convención y no una comprobación, esta página lo indica.

Pruebas#

Nombradas como frases#

Un archivo de prueba dice lo que prueba, por ejemplo test_a_card_is_closed_only_when_its_work_merges.py, para que buscar un comportamiento en la suite encuentre la prueba que lo sostiene.

En ambos órdenes y en paralelo#

La suite se ejecuta en orden aleatorio de forma predeterminada (pytest-randomly) y en paralelo (pytest-xdist). A quienes contribuyen se les pide ejecutarla en paralelo tanto en orden aleatorio como en orden fijo (-p no:randomly). Un fallo que depende del orden se trata como una fuga de estado, no como inestabilidad. La CI ejecuta el orden aleatorio, dividida en fragmentos; no ejecuta el orden fijo. El conftest registra la semilla de cada ejecución para poder reproducir un orden.

Guardas probadas por mutación#

tools/mutate.py ejecuta un plan de mutación: cada plan nombra una prueba y una lista de ediciones exactas del código, y cada edición debe poner esa prueba en rojo. Se niega a empezar salvo que el ancla de cada edición coincida exactamente una vez y la línea base esté en verde.

• El ejecutor es seguro ante caídas. Antes de mutar un archivo, guarda una copia fuera del árbol y escribe una nota de operación en curso en la raíz del repositorio; restaura el archivo y comprueba el texto restaurado en un bloque finally. Como un proceso terminado a la fuerza se salta finally, la siguiente ejecución se niega a empezar mientras exista una nota e imprime los comandos que restauran el archivo.
• Los planes de mutación los ejecutan quienes contribuyen, no la CI. Una prueba comprueba que cada plan puede ejecutarse.

Una guarda lee la cosa, no un texto sobre la cosa#

Una prueba que protege una configuración la ejecuta o la analiza: ejecuta el script y lee sus argumentos, o carga el YAML y lee la clave. Cuando hay que buscar en texto, primero se eliminan los comentarios.

Una suite hermética#

• Las credenciales reales se eliminan del entorno antes de la recolección y de nuevo antes de cada prueba: variables de la plataforma Git, del chat, del motor, del harness y de la nube, y la configuración BEEVERFORGE_* del propio operador.
• La suite se ejecuta con su propio HOME, con uno nuevo para cada prueba, y con la sesión de gh oculta. El registro de proyectos es un directorio temporal, nuevo para cada prueba.
• Ninguna prueba llega a un motor real: conectarse a Temporal lanza un error, salvo en las pruebas marcadas owns_its_engine, que inician y eliminan su propio servidor efímero.
• La suite hace commits con su propia identidad de git.

Las dependencias externas opcionales se omiten en tiempo de ejecución#

La falta de una herramienta opcional, como Docker o node, hace que una prueba se omita al ejecutarse; nunca cambia lo que se recolecta. La CI define TEST_REQUIRE_DOCKER, que allí convierte la omisión por Docker en un fallo. El servidor de pruebas de Temporal es un requisito obligatorio, no una omisión.

La CI se atiene al Makefile y cada prueba se ejecuta una vez#

• Cada paso de la CI que prueba o analiza ejecuta un objetivo de make (install, lint, test-collect, test-unit en cuatro fragmentos, test-integration, test-alone, test-ran-once). Los demás pasos obtienen el código, preparan las herramientas, mueven artefactos entre jobs o informan de si todos los jobs pasaron.
• Una guarda expande con make -n los objetivos que nombra la CI y comprueba que siguen ejecutando la suite y analizando cada raíz que cubre la suite. Ninguna guarda prohíbe un paso de CI que no sea un objetivo de make.
• La suite se recolecta una vez; cada fragmento registra los ids de las pruebas que ejecutó; scripts/every_test_ran_once.py falla ante una prueba que falta, se duplica o es desconocida. Una recolección vacía es un fallo, no un éxito.

Linters y comprobación de tipos#

make lint ejecuta ruff y shellcheck. mypy y bandit están configurados en pyproject.toml e instalados con el extra de desarrollo, pero ninguno se ejecuta en el Makefile ni en la CI; no se hacen cumplir.

Código y documentación#

De estas tres reglas solo el fragmento del registro de cambios se comprueba, mediante un workflow. Las otras dos son convenciones documentadas, en CONTRIBUTING.md y docs/adr/README.md.

• Los comentarios dicen por qué, con la medición: la fecha, el código de salida o el incidente que hizo necesaria la línea.
• Fragmentos del registro de cambios. Un pull request que cambia el comportamiento añade changes/<issue>.<type>.md, donde el tipo es uno de highlight, behaviour, fix, security, upgrade o limitation. Un workflow comprueba cada pull request; uno que solo cambia documentación o pruebas lleva en su lugar la etiqueta no-release-note.
• Los registros de decisión se modifican en el mismo archivo. Cuando una decisión cambia, se edita el ADR con una nota fechada que nombra el pull request. Un ADR nuevo sustituye a uno antiguo solo cuando la decisión se revierte, no cuando se precisa.

Publicaciones y versiones#

Estas reglas son convenciones documentadas, escritas en docs/RELEASING.md. El workflow de publicación se ejecuta con cualquier etiqueta que empiece por v y no las comprueba, y el ensayo de instalación se ejecuta después de la publicación, no antes. Lo que sí se comprueba aparece en Guardas de publicación.

• Las versiones son versiones semánticas anteriores a 1.0. Una versión menor incluye funcionalidades y cambios de comportamiento; un parche incluye solo correcciones y se etiqueta en su rama release/x.y, nunca en main.
• Una versión candidata se etiqueta vx.y.z-rc.N y se publica como versión preliminar; las instalaciones siguen resolviendo la última versión final salvo que se nombre la candidata. Una versión menor siempre pasa por al menos una candidata.
• El paquete declara exactamente la etiqueta sin su v, y, cuando la publicación en PyPI está habilitada, el workflow de publicación rechaza una etiqueta que el paquete no declara. Cada cambio de versión regenera la descripción OpenAPI versionada en el mismo commit.
• La versión final se etiqueta en el commit sobre el que se verificó la última candidata, más el commit que declara la versión y sus notas.
• Una versión publicada queda congelada: ninguna etiqueta se mueve, se borra ni se vuelve a subir. La actualización debe ensayarse antes de cada etiqueta. Los defectos de seguridad siguen una vía de aviso privado. Solo el responsable de versiones crea una rama de versión o una etiqueta.

Guardas de publicación#

• El wheel. Una prueba construye un wheel real a partir de una copia limpia del árbol y comprueba que incluye LICENSE y NOTICE, que su único script de consola es beeverforge, que su descripción larga es la página declarada y que contiene todos los archivos de datos que la plataforma necesita en tiempo de ejecución.
• La descripción de la API. docs/reference/openapi.json debe ser igual a lo que genera la aplicación.

Licencia y nombre#

El núcleo tiene licencia Apache-2.0. No hay acuerdo de licencia para contribuyentes: la licencia ya establece qué ocurre con una contribución, y los derechos de autor siguen siendo de quien la escribe. El archivo NOTICE separa el código del nombre: la licencia no concede ningún derecho sobre el nombre, el logotipo ni las marcas BeeverForge, y solo las compilaciones que superan la suite de conformidad publicada (beeverforge conformance, beeverforge conformance-adapter) pueden llamarse BeeverForge.

Registros de decisión de arquitectura#

La columna de estado refleja el código en el commit fijado. Cuando la línea de estado del propio registro y el código no coinciden, se usa el código: «implementado en parte» significa que una parte de la decisión está en el código y otra no.