Une modification n’est pas terminée parce qu’elle fonctionne lors d’une démonstration, parce qu’un test manuel a produit le résultat attendu ou parce que le code est arrivé dans la branche principale. Ces signaux peuvent confirmer une partie de l’implémentation, mais ils ne prouvent pas que la modification est sûre, compréhensible et exploitable en production.
La Definition of Done dans les projets PHP doit établir quelles preuves rendent une modification donnée acceptable. Elle doit couvrir le comportement métier, mais aussi les données existantes, les tâches asynchrones, les intégrations, les permissions, l’observabilité et le retour en arrière. Cela évite que le produit accepte un élément que les opérations ne peuvent pas prendre en charge ou que la technologie déploie une modification dont les effets sont difficiles à réparer.
Ne pas confondre acceptation, implémentation et exploitation
Il est utile de séparer trois états souvent condensés dans un unique « fait » :
- Périmètre accepté : il a été vérifié que la règle métier convenue se comporte comme prévu dans les scénarios pertinents.
- Implémentation terminée : le code, les tests, la configuration et les modifications de schéma nécessaires sont prêts et revus.
- Modification exploitable : elle peut être déployée, surveillée, prise en charge et, si nécessaire, limitée ou annulée sans laisser le système dans un état inconnu.
Dans une application PHP existante, la distance entre ces états peut être considérable. Une nouvelle validation dans un contrôleur peut passer une démonstration, mais bloquer une automatisation qui utilise la même API. Une migration peut s’exécuter sans erreur et pourtant transformer des valeurs qu’un processus d’importation interprète encore selon la sémantique antérieure. Une permission ajoutée dans l’interface peut ne pas s’appliquer à une route interne ou à une commande de console.
La définition ne doit pas devenir un rituel uniforme. Elle doit être proportionnée au risque : un ajustement visuel isolé requiert moins de preuves qu’une modification de la facturation, des permissions, des données personnelles ou de flux produisant des effets externes.
Construire une matrice de critères selon l’impact
Avant de développer, classez la modification selon ses surfaces d’impact. Il n’est pas nécessaire d’attribuer un score complexe : il suffit d’identifier quelles dimensions changent et quelle défaillance serait inacceptable. Chaque dimension active des critères et des preuves supplémentaires.
Métier et comportement
Définissez les règles, les exceptions et les états limites avec des exemples vérifiables. Incluez ce qui doit se produire face à des données incomplètes, des requêtes répétées, de la concurrence et des erreurs prévisibles. Si une règle en remplace une autre, précisez à partir de quand elle s’applique et ce qui arrive aux enregistrements créés sous la règle précédente.
Données et schéma
S’il existe des migrations, de nouveaux champs, un recalcul d’informations ou des importations, déterminez le volume affecté, la compatibilité temporaire entre les versions de l’application et du schéma, ainsi que la validation ultérieure. Une migration terminée n’équivaut pas à des données correctes : il faut vérifier les décomptes, les valeurs invalides, les doublons, les valeurs nulles inattendues et la préservation des relations pertinentes.
Intégrations et processus asynchrones
Les files d’attente, cron, webhooks, e-mails, stockage de fichiers et API externes requièrent leurs propres critères. Documentez les contrats d’entrée et de sortie, les relances, l’idempotence, les délais d’attente, le traitement des réponses partielles ainsi que le traitement et l’acheminement des erreurs. En PHP, une commande de console ou un worker peut utiliser des services et des identifiants différents de ceux d’une requête web ; le test doit couvrir cette exécution réaliste.
Permissions, sécurité et confidentialité
Indiquez qui peut voir, créer, approuver, modifier ou exporter chaque ressource. L’autorisation doit être vérifiée sur le serveur, et pas seulement au moyen de la visibilité d’un bouton. Si des données personnelles ou des secrets opérationnels interviennent, incluez la minimisation des journaux, les restrictions d’accès et la révision des informations qui apparaissent dans les erreurs, les traces et les notifications.
Exploitation et déploiement
Déterminez comment une défaillance sera détectée après le déploiement : journaux contextualisés, métriques existantes, alertes applicables ou vérifications manuelles précises. Distinguez le déploiement de la release : le premier installe les artefacts et la configuration ; la seconde expose le comportement aux utilisateurs ou aux processus. Lorsque cela est possible, une configuration, une activation progressive ou une condition métier peut permettre de limiter l’exposition sans la confondre avec un retour en arrière complet.
Quelles preuves doivent accompagner la modification
Une liste de critères de fin est utile si elle demande des preuves observables, et non des formules vagues telles que « validé » ou « documenté ». La preuve doit pouvoir être examinée par la personne qui accepte la modification et servir pendant un incident.
- Tests automatisés : cas unitaires pour les règles isolées, tests d’intégration pour la persistance, les autorisations et les services, et tests de bout en bout uniquement là où ils apportent une couverture réelle du flux.
- Vérification d’acceptation : scénarios métier exécutés avec des entrées, des résultats et des rôles identifiés, y compris les cas de rejet.
- Résultat de migration : plan d’exécution, validations avant et après, décomptes attendus et traitement explicite des anomalies.
- Contrat d’intégration : modifications des champs, codes d’erreur, authentification, limites, relances et compatibilité avec les consommateurs existants.
- Vérification opérationnelle : quel journal, quelle métrique ou quelle requête permet de confirmer que le flux fonctionne après le déploiement et qui doit le vérifier.
- Guide de support : symptômes connus, identifiants à rechercher, actions sûres et escalade. Il doit être bref et accessible, et non une documentation générique qui n’aide pas sous pression.
Toutes les preuves ne doivent pas être un document indépendant. Un ensemble de tests, une note de déploiement et une requête de validation peuvent suffire s’ils sont précis, localisables et maintenus avec la modification.
Critères minimaux et critères renforcés
Pour une modification à faible risque, sans modification de données, d’interfaces externes ni de permissions, le minimum inclut généralement un périmètre accepté, une revue de code, des tests pertinents, une configuration identifiée et une vérification après le déploiement. Même dans ce cas, ce qui est considéré comme un comportement correct doit être clair.
Ajoutez des contrôles renforcés lorsqu’une quelconque de ces conditions existe :
- Des données persistantes sont créées, transformées ou supprimées.
- Une règle ayant un impact économique, contractuel ou de conformité est modifiée.
- Les rôles, permissions, l’authentification ou l’exposition d’informations sont modifiés.
- Des effets sont envoyés à des systèmes externes, tels que des encaissements, e-mails ou webhooks.
- La modification affecte des workers, des files d’attente, des tâches planifiées ou des processus pouvant se répéter.
- Le déploiement exige une coordination entre l’application, la base de données, l’infrastructure ou les fournisseurs.
Dans ces cas, incluez la compatibilité entre les versions, un plan de déploiement ordonné, des validations de données, un test des défaillances prévisibles, l’observabilité, les responsables de décision et un plan de confinement. La question utile n’est pas « y a-t-il des tests ? », mais « quelle preuve réduirait le risque spécifique de cette modification ? ».
Retour en arrière : reprendre le contrôle, pas faire comme si rien ne s’était passé
Un retour en arrière réaliste dépend des effets produits. Annuler du code peut être simple ; annuler une migration destructive, un e-mail envoyé ou une mise à jour acceptée par une API externe ne l’est pas. C’est pourquoi le critère doit distinguer entre annuler l’exécution future, compenser les effets déjà émis et corriger les données.
Avant la release, définissez le seuil qui imposerait d’agir, qui peut prendre la décision et quelles actions sont sûres. Un indicateur de configuration peut arrêter les nouvelles exécutions. Une file d’attente peut être mise en pause pour éviter davantage d’effets. Une correction compensatoire peut nécessiter une révision humaine avant de modifier des enregistrements déjà traités. S’il n’existe pas de retour en arrière automatique sûr, déclarez-le et préparez une procédure de récupération avec des limites claires.
Un plan de retour en arrière valide identifie les effets irréversibles, la manière de les contenir et les preuves nécessaires pour savoir que le confinement a fonctionné.
Exemple : une nouvelle approbation dans un backoffice PHP
Supposez qu’un backoffice intègre une règle : certaines demandes doivent être approuvées par un rôle spécifique avant de passer à l’exécution. La démonstration peut montrer qu’un bouton apparaît et que l’état passe à « approuvée ». Cela ne suffit pas.
La Definition of Done doit clarifier le modèle d’états : quelles demandes requièrent une approbation, ce qui arrive à celles qui existent déjà, si une approbation peut être révoquée et si deux personnes peuvent agir en même temps. Il faut vérifier que le service de domaine, les contrôleurs, les routes d’API et les commandes de console appliquent la même autorisation. Il faut également vérifier qu’un worker n’exécute pas des demandes en attente sans approbation parce qu’il utilise une requête ancienne.
Si un champ d’état est ajouté, la migration nécessite une règle pour classer les enregistrements historiques et une vérification ultérieure des décomptes. Les journaux d’audit devraient conserver l’acteur, le moment, la transition et le motif lorsque cela s’applique, en évitant d’inclure des informations sensibles inutiles. Les opérations doivent savoir comment détecter des demandes bloquées dans l’attente d’une approbation et comment arrêter le traitement si une transition incohérente apparaît. Le retour en arrière pourrait désactiver l’exigence pour les nouvelles demandes, mais il ne devrait pas supprimer les approbations déjà enregistrées sans décision explicite.
Intégrer les critères dans le cycle de livraison
La Definition of Done ne doit pas être rédigée à la fin comme une liste permettant de clôturer une tâche. Lors du raffinement, le produit et la technologie identifient les règles, dépendances, données affectées et conséquences opérationnelles. Avant de développer, ils conviennent des scénarios d’acceptation et des preuves requises. Pendant l’implémentation, ces preuves guident les tests, migrations, l’instrumentation et la documentation minimale. Avant le déploiement, il est confirmé que l’ordre d’exécution, les responsables et le confinement restent valides.
Évitez trois anti-patterns : des listes génériques qui ignorent le risque ; des critères découverts lorsque la modification est déjà prête à être déployée ; et une documentation étendue sans signaux exploitables pour le support. Une bonne Definition of Done dans les projets PHP n’ajoute pas de bureaucratie par défaut. Elle rend explicite ce qui doit être vrai pour qu’une modification puisse être exploitée en toute sécurité après la fin de la démonstration.
