Zmiana nie jest ukończona dlatego, że działa na demonstracji, ręczny test dał oczekiwany wynik lub kod trafił do głównej gałęzi. Te sygnały mogą potwierdzać część implementacji, ale nie dowodzą, że zmiana jest bezpieczna, zrozumiała i możliwa do obsługi na produkcji.
Definicja ukończenia w projektach PHP powinna określać, jakie dowody czynią konkretną zmianę akceptowalną. Powinna obejmować zachowanie biznesowe, ale także istniejące dane, zadania asynchroniczne, integracje, uprawnienia, obserwowalność i wycofanie. Pozwala to uniknąć sytuacji, w której produkt akceptuje coś, czego operacje nie są w stanie utrzymać, albo technologia wdraża modyfikację, której skutki są trudne do naprawienia.
Nie myl akceptacji, implementacji i operacji
Warto rozdzielić trzy stany, które często sprowadza się do jednego „gotowe”:
- Zaakceptowany zakres: potwierdzono, że uzgodniona reguła biznesowa zachowuje się zgodnie z oczekiwaniami w istotnych scenariuszach.
- Ukończona implementacja: kod, testy, konfiguracja i niezbędne zmiany schematu są gotowe i zrecenzowane.
- Zmiana operacyjna: można ją wdrożyć, monitorować, wspierać oraz, jeśli to konieczne, ograniczyć lub wycofać bez pozostawienia systemu w nieznanym stanie.
W istniejącej aplikacji PHP odległość między tymi stanami może być znaczna. Nowa walidacja w kontrolerze może przejść demonstrację, lecz zablokować automatyzację korzystającą z tego samego API. Migracja może wykonać się bez błędów, a mimo to przekształcić wartości, które proces importu nadal interpretuje według wcześniejszej semantyki. Uprawnienie dodane w interfejsie może nie być stosowane do wewnętrznego endpointu API lub polecenia konsolowego.
Definicja nie powinna stać się jednolitym rytuałem. Musi być proporcjonalna do ryzyka: odizolowana korekta wizualna wymaga mniej dowodów niż zmiana dotycząca rozliczeń, uprawnień, danych osobowych lub przepływów z efektami zewnętrznymi.
Budowanie macierzy kryteriów według wpływu
Przed rozpoczęciem prac sklasyfikuj zmianę według obszarów jej wpływu. Nie trzeba przypisywać złożonej punktacji: wystarczy wskazać, które wymiary się zmieniają i która awaria byłaby nieakceptowalna. Każdy wymiar aktywuje dodatkowe kryteria i dowody.
Biznes i zachowanie
Określ reguły, wyjątki i stany graniczne za pomocą weryfikowalnych przykładów. Uwzględnij, co ma się wydarzyć przy niekompletnych danych, powtarzających się żądaniach, współbieżności i przewidywalnych błędach. Jeśli jedna reguła zastępuje inną, sprecyzuj, od kiedy obowiązuje i co dzieje się z rekordami utworzonymi według poprzedniej reguły.
Dane i schemat
Jeśli występują migracje, nowe pola, ponowne obliczanie informacji lub importy, określ objętość danych, tymczasową kompatybilność między wersjami aplikacji i schematu oraz walidację po wykonaniu. Ukończona migracja nie jest równoznaczna z poprawnymi danymi: należy sprawdzić liczności, nieprawidłowe wartości, duplikaty, nieoczekiwane wartości null oraz zachowanie istotnych relacji.
Integracje i procesy asynchroniczne
Kolejki, cron, webhooki, e-maile, przechowywanie plików i zewnętrzne API wymagają własnych kryteriów. Udokumentuj kontrakty wejścia i wyjścia, ponowne próby, idempotencję, limity czasu, obsługę częściowych odpowiedzi oraz to, dokąd wysyłane są błędy. W PHP polecenie konsolowe lub worker może korzystać z innych usług i poświadczeń niż żądanie webowe; test powinien obejmować to realistyczne wykonanie.
Uprawnienia, bezpieczeństwo i prywatność
Wskaż, kto może wyświetlać, tworzyć, zatwierdzać, modyfikować lub eksportować każdy zasób. Autoryzację należy weryfikować po stronie serwera, a nie tylko poprzez widoczność przycisku. Jeśli dotyczą tego dane osobowe lub tajemnice operacyjne, uwzględnij minimalizację logów, ograniczenia dostępu oraz przegląd informacji pojawiających się w błędach, śladach i powiadomieniach.
Operacje i wdrożenie
Określ, jak zostanie wykryta awaria po wdrożeniu: logi z kontekstem, istniejące metryki, mające zastosowanie alerty lub konkretne kontrole ręczne. Rozróżniaj wdrożenie od release: pierwsze instaluje artefakty i konfigurację, drugie udostępnia zachowanie użytkownikom lub procesom. Gdy jest to możliwe, konfiguracja, stopniowe udostępnianie lub warunek biznesowy mogą pozwolić ograniczyć ekspozycję bez mylenia tego z pełnym wycofaniem.
Jakie dowody powinny towarzyszyć zmianie
Lista ukończenia jest użyteczna, jeśli wymaga obserwowalnych dowodów, a nie ogólnikowych formuł, takich jak „zwalidowano” czy „udokumentowano”. Dowód powinien móc zostać sprawdzony przez osobę akceptującą zmianę i być przydatny podczas incydentu.
- Testy automatyczne: przypadki jednostkowe dla odizolowanych reguł, testy integracyjne dla persystencji, autoryzacji i usług oraz testy end-to-end tylko tam, gdzie zapewniają rzeczywiste pokrycie przepływu.
- Weryfikacja akceptacyjna: scenariusze biznesowe wykonane z określonymi danymi wejściowymi, wynikami i rolami, w tym przypadki odrzucenia.
- Wynik migracji: plan wykonania, walidacje przed i po, oczekiwane liczności oraz jawne postępowanie z anomaliami.
- Kontrakt integracyjny: zmiany w polach, kodach błędów, uwierzytelnianiu, limitach, ponownych próbach i kompatybilności z istniejącymi konsumentami.
- Weryfikacja operacyjna: który log, metryka lub zapytanie pozwala potwierdzić, że przepływ działa po wdrożeniu, oraz kto powinien to sprawdzić.
- Przewodnik wsparcia: znane symptomy, identyfikatory do wyszukania, bezpieczne działania i eskalacja. Powinien być krótki i dostępny, a nie stanowić ogólną dokumentację, która nie pomaga pod presją.
Nie każdy dowód musi być osobnym dokumentem. Zestaw testów, notatka wdrożeniowa i zapytanie walidacyjne mogą wystarczyć, jeśli są precyzyjne, możliwe do zlokalizowania i utrzymywane razem ze zmianą.
Kryteria minimalne i wzmocnione
W przypadku zmiany o niskim ryzyku, bez modyfikacji danych, zewnętrznych interfejsów ani uprawnień, minimum zwykle obejmuje zaakceptowany zakres, przegląd kodu, istotne testy, zidentyfikowaną konfigurację i kontrolę po wdrożeniu. Nawet tutaj musi być jasne, co uznaje się za prawidłowe zachowanie.
Dodaj wzmocnione kontrole, gdy występuje którykolwiek z tych warunków:
- Tworzone, przekształcane lub usuwane są trwałe dane.
- Modyfikowana jest reguła mająca wpływ ekonomiczny, umowny lub zgodnościowy.
- Zmieniane są role, uprawnienia, uwierzytelnianie lub ekspozycja informacji.
- Wysyłane są efekty do systemów zewnętrznych, takie jak obciążenia, e-maile lub webhooki.
- Zmiana wpływa na workery, kolejki, zadania zaplanowane lub procesy, które mogą się powtarzać.
- Wdrożenie wymaga koordynacji między aplikacją, bazą danych, infrastrukturą lub dostawcami.
W tych przypadkach uwzględnij kompatybilność między wersjami, uporządkowany plan wdrożenia, walidacje danych, test przewidywalnych awarii, obserwowalność, osoby odpowiedzialne za decyzje i plan ograniczenia skutków. Użyteczne pytanie nie brzmi „czy są testy?”, lecz „jaki dowód zmniejszyłby konkretne ryzyko tej zmiany?”.
Wycofanie: odzyskać kontrolę, a nie udawać, że nic się nie stało
Realistyczne wycofanie zależy od wywołanych skutków. Wycofanie kodu może być proste; wycofanie destrukcyjnej migracji, wysłanego e-maila lub aktualizacji zaakceptowanej przez zewnętrzne API już nie. Dlatego kryterium powinno rozróżniać wycofanie przyszłego wykonania, skompensowanie już wyemitowanych skutków oraz korektę danych.
Przed udostępnieniem wersji określ próg wymagający działania, kto może podjąć decyzję i które działania są bezpieczne. Flaga konfiguracyjna może zatrzymać nowe wykonania. Kolejkę można wstrzymać, aby zapobiec kolejnym skutkom. Korekta kompensacyjna może wymagać przeglądu przez człowieka przed zmodyfikowaniem już przetworzonych rekordów. Jeśli nie ma bezpiecznego automatycznego wycofania, zaznacz to i przygotuj procedurę odzyskiwania z jasnymi ograniczeniami.
Właściwy plan wycofania wskazuje nieodwracalne skutki, sposób ich ograniczenia oraz dowody potrzebne do stwierdzenia, że ograniczenie zadziałało.
Przykład: nowe zatwierdzanie w backoffice PHP
Załóżmy, że backoffice wprowadza regułę: określone wnioski muszą zostać zatwierdzone przez konkretną rolę, zanim przejdą do wykonania. Demonstracja może pokazać, że pojawia się przycisk, a stan zmienia się na „zatwierdzony”. To nie wystarcza.
Definicja ukończenia musi wyjaśniać model stanów: które wnioski wymagają zatwierdzenia, co dzieje się z już istniejącymi, czy zatwierdzenie można cofnąć i czy dwie osoby mogą działać jednocześnie. Należy zweryfikować, że usługa domenowa, kontrolery, trasy API i polecenia konsolowe stosują tę samą autoryzację. Trzeba również sprawdzić, czy worker nie wykonuje oczekujących wniosków bez zatwierdzenia z powodu użycia starego zapytania.
Jeśli dodawane jest pole stanu, migracja potrzebuje reguły klasyfikowania rekordów historycznych oraz późniejszej kontroli liczności. Logi audytowe powinny zachowywać aktora, moment, przejście i powód, gdy ma to zastosowanie, bez uwzględniania niepotrzebnych wrażliwych informacji. Operacje muszą wiedzieć, jak wykrywać wnioski zablokowane w oczekiwaniu na zatwierdzenie i jak zatrzymać przetwarzanie, jeśli pojawi się niespójne przejście. Wycofanie mogłoby wyłączyć wymóg dla nowych wniosków, lecz nie powinno usuwać już zarejestrowanych zatwierdzeń bez wyraźnej decyzji.
Włączenie kryteriów do cyklu dostarczania
Definicja ukończenia nie powinna być sporządzana na końcu jako lista do zamknięcia zadania. Podczas refinementu produkt i technologia identyfikują reguły, zależności, dane, których dotyczy zmiana, oraz konsekwencje operacyjne. Przed rozpoczęciem prac uzgadniają scenariusze akceptacyjne i wymagane dowody. Podczas implementacji te dowody ukierunkowują testy, migracje, instrumentację i minimalną dokumentację. Przed wdrożeniem potwierdza się, że kolejność wykonania, osoby odpowiedzialne i ograniczanie skutków nadal są właściwe.
Unikaj trzech antywzorców: ogólnych list ignorujących ryzyko; kryteriów odkrywanych, gdy zmiana jest już gotowa do wdrożenia; oraz obszernej dokumentacji bez praktycznych sygnałów dla wsparcia. Dobra definicja ukończenia w projektach PHP nie dodaje domyślnie biurokracji. Wyraźnie określa, co musi być prawdą, aby zmiana mogła bezpiecznie działać po zakończeniu demonstracji.
