Errores que te dicen qué hacer después

Un mensaje de error que solo enuncia el problema ha hecho la mitad de su trabajo. La otra mitad es decirle a quien lo lee qué pasa a continuación.

Los consumidores de esta API ya lo reciben: un 429 dice que vayas más despacio y reintentes, un 422 nombra los campos que fallaron, un 504 con provider_unavailable dice que no fue culpa tuya y que reintentar es razonable.

Tus propios desarrolladores merecen lo mismo de las excepciones con las que se van a encontrar. Compara:

Malformed provider response.

Malformed provider response: key, created_at

El segundo es el que lanza License::fromProvider(). Nombra los campos que fallaron, de modo que quien lea el log de noche sabe lo que el proveedor omitió sin reproducir nada, y lo hace sin copiar los datos del proveedor en el log. Cuando escribas el mensaje de una excepción, escríbelo para la persona que lo leerá sin ningún otro contexto.

Herramientas que concuerdan consigo mismas

Tres herramientas, tres scripts de composer, los mismos nombres en todos los proyectos que tengas:

{
    "scripts": {
        "format": "./vendor/bin/pint",
        "check": "./vendor/bin/phpstan analyse",
        "test": "./vendor/bin/pest"
    }
}

Pint decide el formato. Su configuración es pint.json: el preset de Laravel más los tipos estrictos, idéntica en todos los repositorios.

{
    "preset": "laravel",
    "rules": {
        "declare_strict_types": true
    }
}

Larastan decide si los tipos se sostienen, al mismo nivel en todas partes.

Esas últimas palabras importan más que el nivel en sí. Si un repositorio ejecuta el análisis estático a nivel 9 y otro a nivel 5, una marca verde significa dos cosas distintas, y un desarrollador que se mueve entre ellos no puede fiarse de ninguna sin consultarlo. Yo he tenido exactamente esa división, una aplicación más antigua y más grande sometida a un listón más bajo que los servicios pequeños que la rodeaban. Había una razón, y aun así era una deuda. Sube el más bajo, o al menos deja por escrito que la diferencia existe.

Unas herramientas consistentes son lo que permite a un desarrollador fiarse de una marca verde sin tener que deducir otra vez qué verificó esa comprobación.

Los mismos tres comandos en CI

El pipeline que protege la rama principal ejecuta los comandos que un desarrollador ejecuta en local: los mismos tres, más una auditoría de dependencias.

# .github/workflows/ci.yml
on:
  push:
    branches: [main]
  pull_request:

permissions:
  contents: read

jobs:
  quality-gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.5'
      - run: composer install --no-interaction
      - run: composer audit
      - run: vendor/bin/pint --test
      - run: composer check
      - run: composer test

pint --test es composer format en su modo de comprobación: falla cuando el formato no está bien y no cambia nada. composer check y composer test son los scripts de arriba. composer audit es el único añadido: hace fallar el build cuando un paquete del que dependes tiene una vulnerabilidad conocida, el mismo día en que se publica el aviso. El bloque permissions le da al token del workflow acceso de lectura y nada más, que es todo lo que necesita un control de calidad. Los tests no necesitan un archivo .env, porque el Capítulo 12 puso todo lo que necesitan, incluida la clave de aplicación, en phpunit.xml.

Cuando CI y un portátil ejecutan los mismos comandos, «pasó en mi máquina» y «pasó en CI» significan lo mismo, y un fallo en uno se reproduce en el otro tecleando una línea.

Lo que queda para quien revisa

Para cuando una persona abre el diff, Pint ha decidido los espacios y las llaves, el análisis estático ha decidido si los tipos se sostienen, y los tests han decidido si el cambio respeta la estructura. Nada de eso necesita un ojo humano, y nada de eso debería abrir una discusión en un pull request.

Lo que queda es lo único que una persona debería revisar: ¿resuelve esto el problema correcto, y hace la lógica lo que dice hacer?

Resumen del capítulo 14

• Primera hora: un README que es un mapa, y comandos en lugar de listas que quedan obsoletas.
• Instalación: un comando, que sigue siendo veraz a medida que el proyecto crece.
• Convenciones: tómalas de Laravel donde puedas. Genera e impón las que sean tuyas.
• Documentación: tests para el comportamiento, tests de arquitectura para la estructura, prosa solo para el porqué.
• Errores: escritos para la persona que los lee sin ningún otro contexto.
• Herramientas: la misma configuración de Pint y el mismo nivel de análisis en todas partes.
• CI: los mismos tres comandos que un desarrollador ejecuta en local.
• Revisiones: la máquina comprueba la forma, para que las personas revisen el significado.