KB Flooris Statamic - Statamic Update Procedures¶

Belangrijk

Tijdens deze update procedures kunnen er project-specifieke errors optreden. Deze verschillen per project en moeten per situatie worden opgelost. Gebruik debugging skills en documentatie om deze op te lossen.

Overzicht¶

Deze handleiding beschrijft het complete proces voor het updaten van Statamic/Laravel projecten binnen Flooris ("update day"). Het proces bestaat uit drie fases — Discovery, Development en QA — en is gebaseerd op de uitgevoerde update-runs voor:
- Ken Aerts Marketing en Communicatie (GB-1574)
- Trampolineingraven (TT-1523)

AI-first uitvoering

Fase 2 (Development) wordt AI-first uitgevoerd: een agent doorloopt de upgrade-stappen op een feature branch en stopt alleen bij expliciete stopmomenten — situaties die een mensbeslissing vereisen (bijv. een addon die niet bestaat in de doelversie). Fase 1 en Fase 3 zijn grotendeels mensenwerk.

Doel: de site na de update functioneel én SEO-technisch identiek laten werken, met bewijs daarvan in de ClickUp-taak.

Scope bepalen¶

Documenteer bij de start van de taak de eindsituatie in een scope-tabel:

Onderdeel	Van	Naar
Statamic CMS	huidige versie	doelversie
Laravel	huidige versie	doelversie
PHP	vaststellen in Discovery	8.x
NodeJS	huidig	laatste LTS
Frontend packages	huidig	laatste stabiele majors
Dependabot	open issues	0 kritiek/hoog open

Buiten scope: nieuwe features, redesign, contentwijzigingen.

Fase 1 — Discovery (max 2u)¶

Doel: voordat je begint weet je exact wat er in dit project zit en wat "goed" is na de update.

Afgerond wanneer: nulmeting-exports als bijlage in de taak staan, PHP- en NodeJS-versie zijn ingevuld, en de scope-tabel is bevestigd of aangepast.

Fase 2 — Development (max 5u)¶

Uitvoering is AI-first. De agent doorloopt onderstaande stappen op een branch feature/{task-id}-major-update-statamic-laravel en stopt bij elk gemarkeerd stopmoment om te rapporteren in de taak.

Shift AI skills

Laravel-upgrades draaien via de Shift AI skills. Shift dekt alleen Laravel — de Statamic-keten is eigen werk volgens de officiële upgrade guide.

Voorbereiding (mens, 15 min)¶

Branch aanmaken vanaf master/development.
Nulmeting-crawl uit Fase 1 lokaal beschikbaar als vergelijkingsbestand.
Shift-plan/account geregeld.

Afgerond wanneer: de site draait op test, de crawl-diff op test toont geen onverklaarde afwijkingen, en elk stopmoment waar de agent is gestopt heeft een expliciete beslissing in een comment.

Fase 3 — QA (max 6u)¶

QA gebeurt in twee ronden: lokaal door de developer, daarna op test door een tweede persoon. Bevindingen altijd als comment in de taak.

Afgerond wanneer: de crawlvergelijking geen onverklaarde afwijkingen bevat en Search Console 14 dagen na livegang geen nieuwe fouten toont.

Visuele regressiecontrole (Playwright)¶

Screaming Frog dekt structuur en SEO-metadata, maar ziet geen lay-out- of stylingbreuk (bijv. een Tailwind-major die class-namen wijzigt, of een addon die zijn eigen CSS anders uitlevert). Gebruik hiervoor een losse Playwright-suite die dezelfde pagina's op productie en op de lokale/test-omgeving vergelijkt via full-page screenshots, pixel-diff en een side-by-side-composite. Deze aanpak is voor het eerst toegepast in het TwinPharma-project (tests/visual-compare/) en is herbruikbaar op andere Statamic-projecten.

Opzet¶

Locatie: eigen map, bijv. tests/visual-compare/, los van eventuele functionele Playwright/E2E-tests.
Vereisten: Node ≥ 20, de lokale/test-omgeving bereikbaar over HTTPS, APP_KEY gezet, en — als statische pagecache aanstaat (STATAMIC_STATIC_CACHING_STRATEGY=full) — de cache geleegd vóórdat je vergelijkt, anders vergelijk je stale gecachte HTML.

Installatie (eenmalig):

yarn install
npx playwright install --with-deps chromium

Configuratie: playwright.config.ts met fullyParallel: false, workers: 1 (voorkomt race conditions tussen screenshots) en een vaste viewport (bijv. 1440×900 desktop).
Routeset: een representatieve steekproef van pagetypes × locales (home, een productdetail, een contentpagina, in elke taal die het project ondersteunt) — geen volledige crawl. Basis-URL's van productie en lokaal/test zijn overschrijfbaar via env vars (PROD_BASE_URL, LOCAL_BASE_URL).
Per route: navigeer naar dezelfde route op beide omgevingen, maak een full-page screenshot, bouw met pixelmatch een diff-afbeelding en een side-by-side-compositie (prod | lokaal | diff), en log het percentage afwijkende pixels.

Ken de valkuilen

networkidle + vaste wait-timer is flaky. Trage prod-CDN's of lazy-loaded content geven anders valse diffs. Wacht liever op een concrete DOM-marker.
Dynamische content vervuilt de diff. Datums, "laatst bijgewerkt"-teksten, cookie-consent-banners of willekeurig getoonde gerelateerde content geven ruis zonder echte regressie. Mask deze elementen (Playwright's mask-optie op page.screenshot()) of sluit de cookiebanner expliciet vóór de screenshot.
Zonder een drempelwaarde faalt de test nooit. Laat het diff-percentage niet alleen loggen — vergelijk het met een geconfigureerde MAX_DIFF_RATIO en laat de test falen als die overschreden wordt, anders is dit een rapportagemiddel en geen kwaliteitspoort.
Productie is een referentiepunt, geen baseline. Bewuste contentwijzigingen tussen nulmeting en update-dag leveren een "verschil" op dat geen regressie is — beoordeel elke afwijking, verklaar 'm in een comment, en neem 'm niet blind als fail.

Resultaten¶

Bewaar per route minimaal de prod-, lokaal- en diff-afbeelding plus de side-by-side-compositie (bijv. onder playwright-report/compare-output/, niet gecommit). Koppel de side-by-side- en diff-afbeeldingen als attachment aan elke Playwright-test zodat ze in het HTML-testrapport zichtbaar zijn, en zet de belangrijkste afbeeldingen als bijlage in de ClickUp-taak — dit is het visuele bewijsstuk naast de Screaming Frog-crawl-diff.

Wanneer inzetten¶

Altijd: in Fase 3 (QA/SEO/techniek) op test, als aanvulling op de crawl-vergelijking, vóór livegang.
Aanbevolen: in Fase 2, na een major met verhoogd stylingrisico (Tailwind/CSS-major, addon met eigen views, grote frontend-dependency bump) — niet per se na elke major, om doorlooptijd te sparen.

Klantcommunicatie¶

Vooraf: mail naar de klant met domein, welke stack geüpdatet wordt, aantal uren, planning en vraag om akkoord. Afsluiten met een interne taakreferentie.
Controleren of dit onder een SLA/overeenkomst valt; zo ja uren verrekenen, zo nee volledige uren rekenen.
Statamic-licentie controleren en indien nodig laten bijwerken voor de doelversie.
Na livegang: mail met wat er is bijgewerkt en het verzoek afwijkingen te melden.
Alle communicatie terugkoppelen in de taak.

Definition of Done¶

Alle drie de fases zijn afgevinkt en de bijbehorende bewijsstukken (crawl-exports, Playwright-screenshots) staan in de taak.
Changes zijn gecommuniceerd via een comment: wat is er gewijzigd t.o.v. productie en hoe is er getest.
Een tweede persoon heeft QA uitgevoerd op test en bevindingen vermeld in de taak.
Pre- en post-release stappen staan in de PR en zijn afgevinkt.
De klant heeft akkoord gegeven vóór livegang en is na livegang geïnformeerd.
Uren zijn geschreven op de taak en de status is bijgewerkt.

Troubleshooting¶

FontAwesome authentication errors

Probleem: yarn install faalt met authenticatie errors.

**Oplossing:** Kopieer de `FONTAWESOME_NPM_AUTH_TOKEN` uit een ander project naar je `.env`.

Docker container start niet

Probleem: Docker compose geeft errors bij opstarten.

**Oplossing:**
```bash
docker compose down
docker system prune -a
docker compose up -d --build
```

Composer install faalt

Probleem: Dependencies kunnen niet geïnstalleerd worden.

**Oplossing:**
```bash
composer clear-cache
composer install --ignore-platform-reqs
```

Laravel- en Statamic-upgrade laten zich niet los committen

Probleem: Shift bumpt statamic/cms zelf al mee om compatibel te zijn met de nieuwe Laravel-major.

**Oplossing:** Dit is acceptabel — meld het expliciet in de taak en handel beide in één commit af in plaats van kunstmatig te splitsen.

Best Practices¶

Tips voor succesvolle updates

Commit vaak: kleine, logische commits per component/major.
Test tussentijds: crawl na elke major tegen de nulmeting, niet pas aan het einde.
Documenteer stopmomenten: elke afwijking of beslissing als comment in de taak, niet stilzwijgend oplossen.
Gebruik Git branches: werk nooit direct op master/development.
Review code: check alle automatische wijzigingen van Shift.
Backup: maak een backup voordat je major updates uitvoert.