Repositorio reproducible y ejecución baseline

1. ¿Qué es un repositorio reproducible?

La reproducibilidad de un repositorio significa que cualquier persona (o cualquier entorno de CI) puede clonar el repositorio y hacer que el proyecto funcione siguiendo unos pasos simples. Sin «hay que tener instalado X», sin «en mi máquina funciona», sin secretos verbales transmitidos solo en persona. Todo lo necesario para arrancar el proyecto debe estar en el propio repositorio.

Para un proyecto Spring Boot esto se traduce en una lista concreta de requisitos:

• El README.md describe claramente los requisitos y los pasos para arrancar.
• El .gitignore excluye los archivos generados (compilados, caché del IDE, variables de entorno locales).
• El Gradle Wrapper (gradlew + gradle/wrapper/) fija la versión de Gradle.
• Existe un smoke-check: una forma rápida de verificar que el proyecto arranca.

2. README.md como contrato

El README.md no es una formalidad ni «algo que hay que rellenar». Es el primer punto de contacto con el proyecto. Cualquiera que abra el repositorio empezará aquí. Un buen README responde a tres preguntas:

1. ¿Qué es esto? — breve descripción del proyecto.
2. ¿Qué hace falta para arrancarlo? — requisitos del sistema (versión de Java, Docker, etc.).
3. ¿Cómo arrancarlo? — comandos exactos, paso a paso.

Para el proyecto ReadLater Starter el README podría lucir así:

# ReadLater Starter

Servicio Spring Boot para guardar y gestionar artículos «para leer después».

## Requisitos

- Java 21+
- Docker (para PostgreSQL local)

## Arranque rápido

```bash
# 1. Clonar el repositorio
git clone https://github.com/tu-usuario/readlater-starter.git
cd readlater-starter

# 2. Levantar la base de datos
docker compose up -d

# 3. Arrancar la aplicación
./gradlew bootRun
```

La aplicación estará disponible en http://localhost:8080

Fíjate en que los comandos son exactos y ejecutables directamente. No «instala Gradle de alguna manera» — el Wrapper lo hace por nosotros. No «configura la base de datos» — Docker Compose se encarga.

3. .gitignore correcto para un proyecto Spring/Gradle

Un .gitignore incorrecto es una fuente continua de problemas: se cuelan en el repositorio archivos de caché, de configuración local, o incluso secretos. El resultado es que los commits se «ensucian» con cambios irrelevantes y el CI se rompe de formas inesperadas.

Para un proyecto Spring Boot con Gradle, el .gitignore mínimo debe excluir:

# Artefactos de compilación Gradle
build/
.gradle/

# Archivos del IDE (IntelliJ IDEA)
.idea/
*.iml
out/

# Variables de entorno locales (¡NUNCA al repositorio!)
.env
*.env.local

# Archivos del SO
.DS_Store
Thumbs.db

La regla más importante: nunca subir archivos .env con secretos reales al repositorio. Las contraseñas de bases de datos, las API keys, los tokens de servicio — todo esto debe estar excluido de forma permanente. Para las variables locales de desarrollo se usa un archivo .env.example sin valores reales, que sí se sube al repositorio como plantilla.

4. Gradle Wrapper

El Gradle Wrapper es una herramienta fundamental para la reproducibilidad. Su función es simple: fija la versión de Gradle para el proyecto y permite ejecutar Gradle sin necesidad de tenerlo instalado globalmente en el sistema.

El Wrapper consta de varios archivos:

gradlew              — script de lanzamiento (Linux/macOS)
gradlew.bat          — script de lanzamiento (Windows)
gradle/
  wrapper/
    gradle-wrapper.jar        — Wrapper en sí mismo
    gradle-wrapper.properties — versión de Gradle y URL de descarga

El archivo clave es gradle-wrapper.properties:

distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-8.12-bin.zip
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

Cuando ejecutas ./gradlew bootRun, el Wrapper comprueba si ya está descargada la versión de Gradle indicada. Si no, la descarga automáticamente. Esto garantiza que todos los desarrolladores y el CI usen exactamente la misma versión de Gradle.

Importante: todos los archivos del Wrapper (gradlew, gradlew.bat, y el contenido de gradle/wrapper/) deben estar en el repositorio. Es la única excepción a la regla «no subir archivos generados»: el Wrapper en sí mismo es parte del proyecto.

5. Smoke-check: verificación de arranque

Un smoke-check (literalmente «prueba de humo») es la verificación más básica de que el proyecto arranca. Su objetivo es responder a la pregunta: «¿La aplicación siquiera levanta?». No prueba la lógica de negocio, no verifica todos los casos — solo comprueba que el proceso de arranque termina con éxito.

Para un proyecto Spring Boot el smoke-check mínimo es:

# Levantar dependencias (base de datos)
docker compose up -d

# Arrancar la aplicación y esperar a que esté lista
./gradlew bootRun &
sleep 15

# Comprobar que responde
curl -f http://localhost:8080/actuator/health

Si el endpoint /actuator/health devuelve HTTP 200 con {"status":"UP"}, el smoke-check ha pasado. Esto se puede ejecutar en CI para verificar que cada commit no rompe el arranque básico.

Para que funcione el endpoint de health hace falta la dependencia spring-boot-starter-actuator:

dependencies {
    // Actuator: expone endpoints de monitoreo, incluido /actuator/health
    implementation(libs.spring.boot.starter.actuator)
}

6. Estructura final del repositorio reproducible

Un repositorio bien organizado para ReadLater Starter tiene esta estructura:

readlater-starter/
├── gradle/
│   └── wrapper/
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── src/
│   ├── main/
│   │   ├── java/
│   │   └── resources/
│   │       └── application.yml
│   └── test/
├── .gitignore
├── .env.example          ← plantilla de variables de entorno
├── build.gradle.kts
├── docker-compose.yml
├── gradlew
├── gradlew.bat
├── README.md             ← contrato del proyecto
└── settings.gradle.kts

Nada de directorios build/, .gradle/ ni .idea/ en el repositorio. Sin archivos .env con secretos reales. Con un README que explica cómo arrancar el proyecto en tres pasos.

7. Errores típicos en el repositorio

Error n.º 1: .gitignore olvidado o incompleto.
Los directorios build/ y .idea/ aparecen en los commits y generan «ruido» constante en los diffs. La solución es añadirlos al .gitignore desde el primer commit y ejecutar git rm -r --cached build/ si ya se subieron por error.

Error n.º 2: el Wrapper no está en el repositorio.
Sin gradlew y gradle/wrapper/, cada desarrollador tiene que tener instalado Gradle globalmente en la versión correcta. Esto destruye la reproducibilidad. Gradlew siempre debe estar en el repositorio.

Error n.º 3: secretos reales en el repositorio.
Una vez que una contraseña o API key llega al historial de Git, ya está comprometida aunque luego se borre. Los secretos van en variables de entorno o en gestores de secretos (Vault, AWS Secrets Manager, etc.), nunca directamente en archivos de configuración que se suben al repositorio.

Error n.º 4: README desactualizado.
El README que describe una versión antigua del proyecto es a veces peor que no tener README: genera confusión y hace perder tiempo. La disciplina es simple: si cambias los requisitos de arranque, actualizas el README en el mismo commit.