Een wijziging is niet klaar omdat deze in een demonstratie werkt, omdat een handmatige test het verwachte resultaat gaf of omdat de code de hoofdbranch heeft bereikt. Die signalen kunnen een deel van de implementatie bevestigen, maar bewijzen niet dat de wijziging veilig, begrijpelijk en operationeel inzetbaar is in productie.
De Definition of Done in PHP-projecten moet vastleggen welk bewijs een concrete wijziging acceptabel maakt. Deze moet de bedrijfsfunctionaliteit omvatten, maar ook bestaande data, asynchrone taken, integraties, rechten, monitoring en terugdraaien. Zo wordt voorkomen dat product iets accepteert wat beheer niet kan ondersteunen, of dat technologie een wijziging uitrolt waarvan de effecten moeilijk te herstellen zijn.
Acceptatie, implementatie en beheer niet verwarren
Het is raadzaam drie statussen te scheiden die vaak worden samengevat in één enkele 'klaar':
- Geaccepteerde scope: er is gecontroleerd dat de overeengekomen bedrijfsregel zich zoals verwacht gedraagt in de relevante gebruiksscenario's.
- Implementatie voltooid: de benodigde code, tests, configuratie en schemawijzigingen zijn voorbereid en beoordeeld.
- Operationele wijziging: deze kan worden uitgerold, bewaakt, ondersteund en, indien nodig, beperkt of teruggedraaid zonder het systeem in een onbekende toestand achter te laten.
In een bestaande PHP-applicatie kan de afstand tussen deze statussen aanzienlijk zijn. Een nieuwe validatie in een controller kan een demonstratie doorstaan, maar een automatisering blokkeren die dezelfde API gebruikt. Een migratie kan zonder fouten worden uitgevoerd en toch waarden transformeren die een importproces nog volgens de eerdere semantiek interpreteert. Een recht dat aan de interface is toegevoegd, wordt mogelijk niet toegepast op een interne route of een consolecommando.
De definitie mag geen uniform ritueel worden. Deze moet evenredig zijn aan het risico: een geïsoleerde visuele aanpassing vereist minder bewijs dan een wijziging in facturering, rechten, persoonsgegevens of processen met externe effecten.
Een matrix met criteria op basis van impact opbouwen
Classificeer de wijziging vóór de ontwikkeling op basis van de impactvlakken. Het is niet nodig een complexe score toe te kennen: het volstaat om vast te stellen welke dimensies veranderen en welk falen onaanvaardbaar zou zijn. Elke dimensie activeert aanvullende criteria en bewijsstukken.
Bedrijfsregels en gedrag
Definieer regels, uitzonderingen en grensgevallen met verifieerbare voorbeelden. Neem op wat er moet gebeuren bij onvolledige data, herhaalde verzoeken, gelijktijdigheid en voorzienbare fouten. Als een regel een andere vervangt, specificeer dan vanaf wanneer deze geldt en wat er gebeurt met records die onder de vorige regel zijn aangemaakt.
Data en schema
Als er migraties, nieuwe velden, herberekening van informatie of imports zijn, bepaal dan het betrokken volume, de tijdelijke compatibiliteit tussen versies van de applicatie en het schema, en de validatie achteraf. Een voltooide migratie staat niet gelijk aan correcte data: aantallen, ongeldige waarden, duplicaten, onverwachte nullwaarden en het behoud van relevante relaties moeten worden gecontroleerd.
Integraties en asynchrone processen
Wachtrijen, cron, webhooks, e-mails, bestandsopslag en externe API's vereisen eigen criteria. Documenteer input- en outputcontracten, herpogingen, idempotentie, time-outs, de behandeling van gedeeltelijke antwoorden en de afhandeling van fouten. In PHP kan een consolecommando of een achtergrondproces andere services en toegangsgegevens gebruiken dan een webverzoek; de test moet die realistische uitvoering dekken.
Rechten, beveiliging en privacy
Geef aan wie elke resource kan bekijken, aanmaken, goedkeuren, wijzigen of exporteren. Autorisatie moet op de server worden geverifieerd, niet alleen via de zichtbaarheid van een knop. Als persoonsgegevens of vertrouwelijke operationele informatie betrokken zijn, neem dan minimalisering van loggegevens, toegangsbeperkingen en een beoordeling op van welke informatie verschijnt in fouten, traceringsgegevens en meldingen.
Beheer en uitrol
Bepaal hoe een fout na de uitrol wordt gedetecteerd: loggegevens met context, bestaande meetwaarden, toepasselijke waarschuwingen of concrete handmatige controles. Maak onderscheid tussen uitrol en release: de eerste installeert artefacten en configuratie; de tweede schakelt het gedrag in voor gebruikers of processen. Waar mogelijk kan een configuratie, gefaseerde activering of bedrijfsvoorwaarde beperken voor wie of wat het nieuwe gedrag wordt ingeschakeld, zonder dit te verwarren met een volledige terugdraaiing.
Welk bewijs moet de wijziging begeleiden
Een Definition-of-Done-lijst is nuttig als deze om waarneembaar bewijs vraagt, niet om vage formuleringen zoals 'gevalideerd' of 'gedocumenteerd'. Het bewijs moet kunnen worden beoordeeld door degene die de wijziging accepteert en bruikbaar zijn tijdens een incident.
- Geautomatiseerde tests: unit tests voor geïsoleerde regels, integratietests voor persistentie, autorisaties en services, en end-to-endtests alleen waar ze daadwerkelijke dekking van de flow bieden.
- Acceptatiecontrole: uitgevoerde bedrijfsscenario's met geïdentificeerde invoer, resultaten en rollen, inclusief afwijzingsgevallen.
- Migratieresultaat: uitvoeringsplan, validaties vóór en na de migratie, verwachte aantallen en expliciete behandeling van afwijkingen.
- Integratiecontract: wijzigingen in velden, foutcodes, authenticatie, limieten, herpogingen en compatibiliteit met bestaande afnemers.
- Operationele verificatie: welk loggegeven, welke meetwaarde of query kan bevestigen dat de flow na de uitrol werkt, en wie deze moet beoordelen.
- Supporthandleiding: bekende symptomen, te zoeken identifiers, veilige acties en escalatie. Deze moet kort en toegankelijk zijn, geen generieke documentatie die onder druk niet helpt.
Niet elk bewijsstuk hoeft een afzonderlijk document te zijn. Een set tests, een uitrolnotitie en een validatiequery kunnen volstaan als ze precies, vindbaar en samen met de wijziging worden onderhouden.
Minimale en aangescherpte criteria
Voor een wijziging met laag risico, zonder aanpassing van data, externe interfaces of rechten, omvat het minimum doorgaans geaccepteerde scope, codereview, relevante tests, geïdentificeerde configuratie en een controle na de uitrol. Ook hier moet duidelijk zijn wat als correct gedrag wordt beschouwd.
Voeg aangescherpte controles toe wanneer een van deze voorwaarden van toepassing is:
- Persistente data wordt aangemaakt, getransformeerd of verwijderd.
- Een regel met economische, contractuele of compliance-impact wordt gewijzigd.
- Rollen, rechten, authenticatie of blootstelling van informatie worden gewijzigd.
- Effecten worden naar externe systemen gestuurd, zoals betalingen, e-mails of webhooks.
- De wijziging heeft invloed op achtergrondprocessen, wachtrijen, geplande taken of processen die herhaald kunnen worden.
- De uitrol vereist coördinatie tussen applicatie, database, infrastructuur of leveranciers.
Neem in deze gevallen compatibiliteit tussen versies, een geordend uitrolplan, datavalidaties, tests van voorzienbare fouten, monitoring, besluitverantwoordelijken en een indammingsplan op. De nuttige vraag is niet 'zijn er tests?', maar 'welk bewijs zou het specifieke risico van deze wijziging verminderen?'.
Terugdraaien: de controle terugwinnen, niet doen alsof er niets is gebeurd
Een realistische terugdraaiing hangt af van de veroorzaakte effecten. Code terugdraaien kan eenvoudig zijn; een destructieve migratie, een verzonden e-mail of een update die door een externe API is geaccepteerd terugdraaien, is dat niet. Daarom moet het criterium onderscheid maken tussen toekomstige uitvoering terugdraaien, reeds verzonden effecten compenseren en data corrigeren.
Definieer vóór de release de drempel die ingrijpen noodzakelijk maakt, wie de beslissing mag nemen en welke acties veilig zijn. Een configuratievlag kan nieuwe uitvoeringen stoppen. Een wachtrij kan worden gepauzeerd om verdere effecten te voorkomen. Een compenserende correctie kan menselijke beoordeling vereisen voordat reeds verwerkte records worden gewijzigd. Als er geen veilige automatische terugdraaiing bestaat, vermeld dit dan en bereid een herstelprocedure met duidelijke grenzen voor.
Een geldig plan voor terugdraaien identificeert de onomkeerbare effecten, de manier om ze in te dammen en het benodigde bewijs om te weten dat de indamming werkte.
Voorbeeld: een nieuwe goedkeuring in een PHP-backoffice
Stel dat een backoffice een regel krijgt: bepaalde verzoeken moeten door een specifieke rol worden goedgekeurd voordat ze ter uitvoering gaan. De demonstratie kan tonen dat er een knop verschijnt en dat de status verandert in 'goedgekeurd'. Dat is niet voldoende.
De Definition of Done moet het statusmodel verduidelijken: welke verzoeken goedkeuring vereisen, wat er gebeurt met reeds bestaande verzoeken, of een goedkeuring kan worden ingetrokken en of twee personen tegelijk kunnen handelen. Er moet worden geverifieerd dat de domeinservice, controllers, API-routes en consolecommando's dezelfde autorisatie toepassen. Ook moet worden gecontroleerd dat een achtergrondproces geen wachtende verzoeken zonder goedkeuring uitvoert doordat dit een oude query gebruikt.
Als een statusveld wordt toegevoegd, heeft de migratie een regel nodig om historische records te classificeren en een controle achteraf van de aantallen. Auditlogs moeten waar van toepassing actor, tijdstip, transitie en reden bewaren, zonder onnodige gevoelige informatie op te nemen. Beheer moet weten hoe verzoeken die in afwachting van goedkeuring zijn vastgelopen kunnen worden gedetecteerd en hoe de verwerking kan worden gestopt als een inconsistente transitie verschijnt. De terugdraaiing zou de verplichting voor nieuwe verzoeken kunnen uitschakelen, maar mag reeds geregistreerde goedkeuringen niet zonder expliciete beslissing verwijderen.
De criteria in de oplevercyclus integreren
De Definition of Done mag niet aan het einde worden opgesteld als een lijst om een taak af te sluiten. Tijdens de uitwerking identificeren product en technologie regels, afhankelijkheden, betrokken data en operationele gevolgen. Vóór de ontwikkeling spreken zij de acceptatiescenario's en het vereiste bewijs af. Tijdens de implementatie sturen die bewijsstukken tests, migraties, instrumentatie en minimale documentatie. Vóór de uitrol wordt bevestigd dat de uitvoeringsvolgorde, de verantwoordelijken en de indamming nog steeds geldig zijn.
Vermijd drie antipatronen: generieke lijsten die het risico negeren; criteria die worden ontdekt wanneer de wijziging al klaar is voor uitrol; en uitgebreide documentatie zonder bruikbare signalen voor support. Een goede Definition of Done in PHP-projecten voegt niet standaard bureaucratie toe. Deze maakt expliciet wat waar moet zijn opdat een wijziging veilig kan opereren nadat de demonstratie is afgelopen.
