Una modifica non è completata perché funziona in una dimostrazione, perché un test manuale ha dato il risultato atteso o perché il codice è arrivato al branch principale. Questi segnali possono confermare una parte dell’implementazione, ma non dimostrano che la modifica sia sicura, comprensibile e operabile in produzione.
La definizione di completamento nei progetti PHP deve stabilire quali evidenze rendono accettabile una modifica concreta. Deve coprire il comportamento di business, ma anche i dati esistenti, le attività asincrone, le integrazioni, i permessi, l’osservabilità e il rollback. In questo modo si evita che il team di prodotto accetti qualcosa che il team operativo non può sostenere o che la tecnologia effettui il deployment di una modifica i cui effetti sono difficili da riparare.
Non confondere accettazione, implementazione e operatività
È opportuno separare tre stati che spesso vengono condensati in un unico «fatto»:
- Ambito accettato: è stato verificato che la regola di business concordata si comporta come previsto negli scenari rilevanti.
- Implementazione completata: il codice, i test, la configurazione e le modifiche allo schema necessarie sono pronti e revisionati.
- Modifica operabile: può essere distribuita, monitorata, supportata e, se necessario, limitata o sottoposta a rollback senza lasciare il sistema in uno stato sconosciuto.
In un’applicazione PHP esistente, la distanza tra questi stati può essere considerevole. Una nuova validazione in un controller può superare una dimostrazione, ma bloccare un’automazione che usa la stessa API. Una migrazione può essere eseguita senza errori e tuttavia trasformare valori che un processo di importazione interpreta ancora secondo la semantica precedente. Un permesso aggiunto nell’interfaccia potrebbe non applicarsi a una route interna o a un comando da console.
La definizione non deve trasformarsi in un rituale uniforme. Deve essere proporzionata al rischio: una modifica visiva isolata richiede meno evidenze di una modifica alla fatturazione, ai permessi, ai dati personali o ai flussi con effetti esterni.
Costruire una matrice di criteri in base all’impatto
Prima di sviluppare, classifichi la modifica in base alle sue superfici di impatto. Non è necessario assegnare un punteggio complesso: basta identificare quali dimensioni cambiano e quale errore sarebbe inaccettabile. Ogni dimensione attiva criteri ed evidenze aggiuntivi.
Business e comportamento
Definisca regole, eccezioni e stati limite con esempi verificabili. Includa cosa deve accadere in presenza di dati incompleti, richieste ripetute, concorrenza ed errori prevedibili. Se una regola sostituisce un’altra, specifichi da quando si applica e cosa accade ai record creati secondo la regola precedente.
Dati e schema
Se sono presenti migrazioni, nuovi campi, ricalcolo di informazioni o importazioni, determini il volume interessato, la compatibilità temporanea tra versioni dell’applicazione e dello schema e la validazione successiva. Una migrazione completata non equivale a dati corretti: occorre controllare conteggi, valori non validi, duplicati, null imprevisti e la preservazione delle relazioni rilevanti.
Integrazioni e processi asincroni
Code, cron, webhook, email, archiviazione di file e API esterne richiedono criteri propri. Documenti contratti di input e output, retry, idempotenza, timeout, gestione delle risposte parziali e destinazione degli errori. In PHP, un comando da console o un worker può usare servizi e credenziali diversi da quelli di una richiesta web; il test deve coprire questa esecuzione realistica.
Permessi, sicurezza e privacy
Indichi chi può visualizzare, creare, approvare, modificare o esportare ciascuna risorsa. L’autorizzazione deve essere verificata sul server, non solo tramite la visibilità di un pulsante. Se sono coinvolti dati personali o segreti operativi, includa minimizzazione dei log, restrizioni di accesso e revisione delle informazioni che compaiono in errori, trace e notifiche.
Operatività e deployment
Stabilisca come verrà rilevato un errore dopo il deployment: log con contesto, metriche esistenti, alert applicabili o controlli manuali concreti. Distingua il deployment dal release: il primo installa artefatti e configurazione; il secondo espone il comportamento a utenti o processi. Quando possibile, una configurazione, un’attivazione graduale o una condizione di business può consentire di limitare l’esposizione senza confonderla con un rollback completo.
Quali evidenze devono accompagnare la modifica
Una checklist di completamento è utile se richiede prove osservabili, non formule vaghe come «validato» o «documentato». L’evidenza deve poter essere revisionata da chi accetta la modifica e servire durante un incidente.
- Test automatizzati: casi unitari per regole isolate, test di integrazione per persistenza, autorizzazioni e servizi, e test end-to-end solo dove forniscano una copertura reale del flusso.
- Verifica di accettazione: scenari di business eseguiti con input, risultati e ruoli identificati, inclusi i casi di rifiuto.
- Risultato della migrazione: piano di esecuzione, validazioni precedenti e successive, conteggi attesi e gestione esplicita delle anomalie.
- Contratto di integrazione: modifiche a campi, codici di errore, autenticazione, limiti, retry e compatibilità con i consumer esistenti.
- Verifica operativa: quale log, metrica o query consente di confermare che il flusso funzioni dopo il deployment e chi debba revisionarlo.
- Guida al supporto: sintomi noti, identificatori da cercare, azioni sicure ed escalation. Deve essere breve e accessibile, non documentazione generica che non aiuta sotto pressione.
Non tutte le evidenze devono essere un documento indipendente. Un insieme di test, una nota di deployment e una query di validazione possono bastare se sono precisi, localizzabili e mantenuti insieme alla modifica.
Criteri minimi e criteri rafforzati
Per una modifica a basso rischio, senza modifica di dati, interfacce esterne o permessi, il minimo di solito include ambito accettato, revisione del codice, test rilevanti, configurazione identificata e un controllo successivo al deployment. Anche in questo caso deve essere chiaro cosa è considerato comportamento corretto.
Aggiunga controlli rafforzati quando esiste una qualsiasi di queste condizioni:
- Vengono creati, trasformati o eliminati dati persistenti.
- Viene modificata una regola con impatto economico, contrattuale o di compliance.
- Vengono modificati ruoli, permessi, autenticazione o esposizione di informazioni.
- Vengono inviati effetti a sistemi esterni, come addebiti, email o webhook.
- La modifica interessa worker, code, attività pianificate o processi che possono ripetersi.
- Il deployment richiede coordinamento tra applicazione, database, infrastruttura o fornitori.
In questi casi, includa compatibilità tra versioni, piano di deployment ordinato, validazioni dei dati, test di errori prevedibili, osservabilità, responsabili delle decisioni e piano di contenimento. La domanda utile non è «ci sono test?», ma «quale evidenza ridurrebbe il rischio specifico di questa modifica?».
Rollback: recuperare il controllo, non fingere che non sia accaduto nulla
Un rollback realistico dipende dagli effetti prodotti. Effettuare il rollback del codice può essere semplice; effettuare il rollback di una migrazione distruttiva, di un’email inviata o di un aggiornamento accettato da un’API esterna non lo è. Per questo il criterio deve distinguere tra effettuare il rollback dell’esecuzione futura, compensare effetti già emessi e correggere i dati.
Prima del release, definisca la soglia che obbligherebbe ad agire, chi può prendere la decisione e quali azioni sono sicure. Un flag di configurazione può arrestare nuove esecuzioni. Una coda può essere messa in pausa per evitare ulteriori effetti. Una correzione compensativa può richiedere una revisione umana prima di modificare record già elaborati. Se non esiste un rollback automatico sicuro, lo dichiari e prepari una procedura di ripristino con limiti chiari.
Un piano di rollback valido identifica gli effetti irreversibili, il modo per contenerli e l’evidenza necessaria per sapere che il contenimento ha funzionato.
Esempio: una nuova approvazione in un backoffice PHP
Supponga che un backoffice introduca una regola: determinate richieste devono essere approvate da un ruolo specifico prima di passare all’esecuzione. La dimostrazione può mostrare che appare un pulsante e che lo stato cambia in «approvata». Questo non basta.
La definizione di completamento deve chiarire il modello degli stati: quali richieste richiedono approvazione, cosa accade a quelle già esistenti, se un’approvazione può essere revocata e se due persone possono agire contemporaneamente. Deve essere verificato che il servizio di dominio, i controller, le route API e i comandi da console applichino la stessa autorizzazione. Occorre inoltre verificare che un worker non esegua richieste in attesa senza approvazione a causa dell’uso di una query precedente.
Se viene aggiunto un campo di stato, la migrazione necessita di una regola per classificare i record storici e di un controllo successivo dei conteggi. I record di audit dovrebbero conservare attore, momento, transizione e motivo quando appropriato, evitando di includere informazioni sensibili non necessarie. Il team operativo deve sapere come rilevare richieste bloccate in attesa di approvazione e come arrestare l’elaborazione se compare una transizione incoerente. Il rollback potrebbe disattivare il requisito per le nuove richieste, ma non dovrebbe eliminare approvazioni già registrate senza una decisione esplicita.
Integrare i criteri nel ciclo di delivery
La definizione di completamento non deve essere redatta alla fine come una lista per chiudere un’attività. Durante il refinement, prodotto e tecnologia identificano regole, dipendenze, dati interessati e conseguenze operative. Prima di sviluppare, concordano gli scenari di accettazione e le evidenze richieste. Durante l’implementazione, tali evidenze guidano test, migrazioni, strumentazione e documentazione minima. Prima del deployment, si conferma che l’ordine di esecuzione, i responsabili e il contenimento siano ancora validi.
Eviti tre antipattern: liste generiche che ignorano il rischio; criteri scoperti quando la modifica è già pronta per il deployment; e documentazione estesa senza segnali azionabili per il supporto. Una buona definizione di completamento nei progetti PHP non aggiunge burocrazia per impostazione predefinita. Rende esplicito ciò che deve essere vero affinché una modifica possa operare in sicurezza dopo che la dimostrazione è terminata.
