Un script de configuración para el primer día que se verifica a sí mismo: bootstrap, doctor y smoke test

Objetivo

Una persona recién incorporada o un agente ejecuta un solo comando después de clonar y termina con un entorno funcional o con una lista precisa de lo que falta y de cómo corregirlo; si se vuelve a ejecutar, el comando informa de que no hay nada que hacer.

Requisitos previos

Una lista de lo que necesita el proyecto: entornos de ejecución y sus versiones, gestores de paquetes, bibliotecas del sistema, servicios (base de datos, cache), credenciales y de dónde se obtienen, y, para cada elemento, una comprobación que demuestre que está presente. El patrón «Scripts To Rule Them All» de GitHub aporta la división que sigue esta metodología: script/bootstrap se usa únicamente para satisfacer las dependencias del proyecto, script/setup deja el proyecto en su estado inicial tras clonarlo, script/update se ejecuta después de un pull y script/test ejecuta la suite de pruebas. El comando doctor de Homebrew, que su página de manual describe como una comprobación de posibles problemas en el sistema que termina con un estado distinto de cero si encuentra alguno, es el modelo para la mitad de verificación.

Pasos

1. Escribe primero el script doctor: una comprobación de solo lectura que imprime una línea por requisito con PASS, FAIL o WARN, el valor encontrado, el valor esperado y el comando para corregirlo. No modifica nada y termina con un código distinto de cero si hay algún FAIL.
2. Escribe bootstrap como una secuencia de pasos idempotentes, cada uno protegido por la comprobación correspondiente de doctor: instala solo lo que falta, toma las versiones del manifiesto de versiones del repositorio y omite lo que ya es correcto.
3. Termina bootstrap ejecutando doctor y después un smoke test: el objetivo de pruebas más rápido, --help del binario compilado o una petición al endpoint de salud local. El código de salida del script es el del smoke test.
4. Haz que todos los pasos sean no interactivos; las solicitudes de entrada bloquean a los agentes y a la CI. Lee las credenciales de variables de entorno o de un archivo documentado, e informa de su ausencia como un FAIL con un enlace, no con una solicitud de entrada.
5. Imprime lo que se hizo y cuánto tardó, y escribe lo mismo en un archivo de registro que una ejecución fallida pueda adjuntar a un informe de error.
6. Ejecuta bootstrap de forma programada en la CI desde una máquina o un contenedor limpios; un script de configuración que solo ejecutan las personas recién incorporadas se deteriora entre una incorporación y otra.
7. Trata cada fallo de una persona recién incorporada como un error de doctor: si ninguna comprobación lo detectó, añade la comprobación antes de arreglar el entorno.

Resultado esperado

Los fallos de configuración pasan a ser específicos («se esperaba PostgreSQL 16, se encontró 14; ejecuta el comando de actualización indicado») en lugar de un stack trace del primer comando que necesitaba la pieza que falta.

Límites y base de verificación

El coste es la cobertura de plataformas: cada sistema operativo compatible requiere mantener sus propias comprobaciones y correcciones. El script no puede verificar lo que no puede observar (una VPN, un permiso concedido en otro lugar); solo puede constatar que una sonda falló. Este es un protocolo propuesto; no se afirma ningún resultado de adopción ni de tiempos.