Un cambio no está terminado porque funcione en una demostración, porque una prueba manual haya dado el resultado esperado o porque el código haya llegado a la rama principal. Esas señales pueden confirmar una parte de la implementación, pero no prueban que el cambio sea seguro, comprensible y operable en producción.
La definición de terminado en proyectos PHP debe establecer qué evidencias hacen aceptable un cambio concreto. Debe cubrir el comportamiento de negocio, pero también los datos existentes, las tareas asíncronas, las integraciones, los permisos, la observabilidad y la vuelta atrás. Así se evita que producto acepte algo que operaciones no puede sostener o que tecnología despliegue una modificación cuyos efectos son difíciles de reparar.
No confundir aceptación, implementación y operación
Conviene separar tres estados que a menudo se condensan en un único «hecho»:
- Alcance aceptado: se ha comprobado que la regla de negocio acordada se comporta como se esperaba en los escenarios relevantes.
- Implementación terminada: el código, las pruebas, la configuración y los cambios de esquema necesarios están preparados y revisados.
- Cambio operable: puede desplegarse, vigilarse, soportarse y, si es necesario, limitarse o revertirse sin dejar el sistema en un estado desconocido.
En una aplicación PHP existente, la distancia entre estos estados puede ser considerable. Una nueva validación en un controlador puede pasar una demostración, pero bloquear una automatización que usa la misma API. Una migración puede ejecutarse sin errores y, sin embargo, transformar valores que un proceso de importación todavía interpreta con la semántica anterior. Un permiso añadido en la interfaz puede no aplicarse a una ruta interna o a un comando de consola.
La definición no debe convertirse en un ritual uniforme. Debe ser proporcional al riesgo: un ajuste visual aislado requiere menos evidencia que un cambio en facturación, permisos, datos personales o flujos con efectos externos.
Construir una matriz de criterios según el impacto
Antes de desarrollar, clasifique el cambio por sus superficies de impacto. No hace falta asignar una puntuación compleja: basta identificar qué dimensiones cambian y qué fallo sería inaceptable. Cada dimensión activa criterios y evidencias adicionales.
Negocio y comportamiento
Defina reglas, excepciones y estados límite con ejemplos verificables. Incluya qué debe ocurrir ante datos incompletos, peticiones repetidas, concurrencia y errores previsibles. Si una regla sustituye a otra, especifique desde cuándo aplica y qué sucede con registros creados bajo la regla anterior.
Datos y esquema
Si hay migraciones, nuevos campos, recalculo de información o importaciones, determine el volumen afectado, la compatibilidad temporal entre versiones de aplicación y esquema, y la validación posterior. Una migración terminada no equivale a datos correctos: hay que comprobar recuentos, valores inválidos, duplicados, nulos inesperados y la preservación de relaciones relevantes.
Integraciones y procesos asíncronos
Colas, cron, webhooks, correos, almacenamiento de archivos y APIs externas requieren criterios propios. Documente contratos de entrada y salida, reintentos, idempotencia, tiempos de espera, tratamiento de respuestas parciales y destino de los errores. En PHP, un comando de consola o un worker puede usar servicios y credenciales distintos a los de una petición web; la prueba debe cubrir esa ejecución realista.
Permisos, seguridad y privacidad
Indique quién puede ver, crear, aprobar, modificar o exportar cada recurso. La autorización debe verificarse en el servidor, no sólo mediante la visibilidad de un botón. Si intervienen datos personales o secretos operativos, incluya minimización de registros, restricciones de acceso y revisión de qué información aparece en errores, trazas y notificaciones.
Operación y despliegue
Determine cómo se detectará un fallo tras el despliegue: registros con contexto, métricas existentes, alertas aplicables o comprobaciones manuales concretas. Distinga despliegue de release: el primero instala artefactos y configuración; el segundo expone el comportamiento a usuarios o procesos. Cuando sea posible, una configuración, una activación gradual o una condición de negocio puede permitir limitar la exposición sin confundirlo con una reversión completa.
Qué evidencias deben acompañar al cambio
Una lista de terminado es útil si pide pruebas observables, no fórmulas vagas como «validado» o «documentado». La evidencia debe poder ser revisada por quien acepta el cambio y servir durante un incidente.
- Pruebas automatizadas: casos unitarios para reglas aisladas, pruebas de integración para persistencia, autorizaciones y servicios, y pruebas de extremo a extremo sólo donde aporten cobertura real del flujo.
- Comprobación de aceptación: escenarios de negocio ejecutados con entradas, resultados y roles identificados, incluidos los casos de rechazo.
- Resultado de migración: plan de ejecución, validaciones previas y posteriores, recuentos esperados y tratamiento explícito de anomalías.
- Contrato de integración: cambios en campos, códigos de error, autenticación, límites, reintentos y compatibilidad con consumidores existentes.
- Verificación operativa: qué registro, métrica o consulta permite confirmar que el flujo funciona tras el despliegue y quién debe revisarlo.
- Guía de soporte: síntomas conocidos, identificadores que buscar, acciones seguras y escalado. Debe ser breve y accesible, no una documentación genérica que no ayuda bajo presión.
No toda evidencia tiene que ser un documento independiente. Un conjunto de pruebas, una nota de despliegue y una consulta de validación pueden bastar si son precisos, localizables y se mantienen junto al cambio.
Criterios mínimos y criterios reforzados
Para un cambio de bajo riesgo, sin modificación de datos, interfaces externas ni permisos, el mínimo suele incluir alcance aceptado, revisión del código, pruebas relevantes, configuración identificada y una comprobación posterior al despliegue. Incluso aquí debe quedar claro qué se considera comportamiento correcto.
Añada controles reforzados cuando exista cualquiera de estas condiciones:
- Se crean, transforman o eliminan datos persistentes.
- Se modifica una regla con impacto económico, contractual o de cumplimiento.
- Se cambian roles, permisos, autenticación o exposición de información.
- Se envían efectos a sistemas externos, como cobros, correos o webhooks.
- El cambio afecta workers, colas, tareas programadas o procesos que pueden repetirse.
- El despliegue exige coordinación entre aplicación, base de datos, infraestructura o proveedores.
En estos casos, incluya compatibilidad entre versiones, plan de despliegue ordenado, validaciones de datos, prueba de fallos previsibles, observabilidad, responsables de decisión y plan de contención. La pregunta útil no es «¿hay pruebas?», sino «¿qué evidencia reduciría el riesgo específico de este cambio?».
Reversión: recuperar control, no fingir que nada ocurrió
Una reversión realista depende de los efectos producidos. Revertir código puede ser sencillo; revertir una migración destructiva, un correo enviado o una actualización aceptada por una API externa no lo es. Por eso el criterio debe distinguir entre revertir la ejecución futura, compensar efectos ya emitidos y corregir datos.
Antes del release, defina el umbral que obligaría a actuar, quién puede tomar la decisión y qué acciones son seguras. Una bandera de configuración puede detener nuevas ejecuciones. Una cola puede pausarse para evitar más efectos. Una corrección compensatoria puede requerir revisión humana antes de modificar registros ya procesados. Si no hay reversión automática segura, declárelo y prepare un procedimiento de recuperación con límites claros.
Un plan de reversión válido identifica los efectos irreversibles, la forma de contenerlos y la evidencia necesaria para saber que la contención funcionó.
Ejemplo: una nueva aprobación en un backoffice PHP
Suponga que un backoffice incorpora una regla: determinadas solicitudes deben ser aprobadas por un rol específico antes de pasar a ejecución. La demostración puede mostrar que aparece un botón y que el estado cambia a «aprobada». Eso no basta.
La definición de terminado debe aclarar el modelo de estados: qué solicitudes requieren aprobación, qué ocurre con las ya existentes, si una aprobación puede revocarse y si dos personas pueden actuar a la vez. Debe verificarse que el servicio de dominio, los controladores, las rutas de API y los comandos de consola aplican la misma autorización. También debe comprobarse que un worker no ejecuta solicitudes pendientes sin aprobación por usar una consulta antigua.
Si se añade un campo de estado, la migración necesita una regla para clasificar los registros históricos y una comprobación posterior de los recuentos. Los registros de auditoría deberían conservar actor, momento, transición y motivo cuando proceda, evitando incluir información sensible innecesaria. Operaciones necesita saber cómo detectar solicitudes atascadas en espera de aprobación y cómo detener el procesamiento si aparece una transición incoherente. La reversión podría desactivar la exigencia para nuevas solicitudes, pero no debería borrar aprobaciones ya registradas sin una decisión explícita.
Integrar los criterios en el ciclo de entrega
La definición de terminado no debe redactarse al final como una lista para cerrar una tarea. Durante el refinamiento, producto y tecnología identifican reglas, dependencias, datos afectados y consecuencias operativas. Antes de desarrollar, acuerdan los escenarios de aceptación y las evidencias requeridas. Durante la implementación, esas evidencias guían pruebas, migraciones, instrumentación y documentación mínima. Antes del despliegue, se confirma que el orden de ejecución, los responsables y la contención siguen siendo válidos.
Evite tres antipatrones: listas genéricas que ignoran el riesgo; criterios descubiertos cuando el cambio ya está listo para desplegar; y documentación extensa sin señales accionables para soporte. Una buena definición de terminado en proyectos PHP no añade burocracia por defecto. Hace explícito lo que debe ser cierto para que un cambio pueda operar con seguridad después de que la demostración haya terminado.
