Deze pagina is een zusterpagina van De basis van packageontwikkeling. Ze gaat uit van basiskennis van packageontwikkeling (service providers, de opbouw van
composer.json, enz.).Omgaan met major-upgrades van Laravel
Het stappenplan
1
Werk de require in composer.json bij
Voeg de nieuwe versie toe aan het dependencybereik. Als je oudere versies blijft ondersteunen, zet je ze naast elkaar met Als de ondersteuning voor de nieuwe versie klaar is en je de oude versie niet langer ondersteunt, verwijder je de oude constraint.
||.2
Draai de tests op de nieuwe versie
Voer de tests lokaal of in CI uit met de nieuwe Laravel-versie.Als de tests slagen, is de basiscompatibiliteit bevestigd. Zo niet, dan pas je gewijzigde API’s en verwijderde methodes aan.
3
Voeg de nieuwe versie toe aan de testmatrix van GitHub Actions
Voeg de nieuwe Laravel-versie toe aan de CI-testmatrix om de compatibiliteit continu te controleren. Zie het voorbeeld van een testmatrixconfiguratie voor details.
4
Breng de release met ondersteuning voor de nieuwe versie uit
Tag en release een nieuwe versie met de wijzigingen in
composer.json. Gebruikers kunnen dan met alleen composer update op de nieuwe Laravel-versie installeren.Officiële packages als referentie
Als je twijfelt over de aanpak, is het raadplegen van decomposer.json van de officiële Laravel-packages de betrouwbaarste route.
Deze packages worden beheerd door het Laravel-team, ondersteunen nieuwe versies het snelst en zijn ook een goede referentie voor hoe je de illuminate/*-versieconstraints noteert.
PHP-versievereisten bijwerken
Een Laravel-upgrade verhoogt soms ook de minimale PHP-vereiste. Werk de PHP-vereiste in decomposer.json van je package dan mee bij.
Als je nieuwe PHP-features actief wilt gebruiken
Wil je features van PHP 8.3 en later gebruiken (getypte constanten, nieuwe randomfuncties, enz.), dan moet je beslissen om de minimale vereiste te verhogen. Het verhogen van de minimale vereiste is volgens semantische versionering een breaking change, dus doe dit bij een major-upgrade.Strategie voor het stopzetten van oude versies
Oude versies eindeloos blijven onderhouden vergroot op de lange termijn de onderhoudskosten. Een duidelijk supportbeleid vastleggen en regelmatig de ondersteuning van oude versies stopzetten leidt tot een gezond packagebeheer.Wanneer stop je met ondersteuning?
Een gangbare aanpak is aansluiten bij de supportperiode van Laravel. Laravel biedt per versie 18 maanden bugfixes en 2 jaar securityfixes. Als je package hetzelfde beleid hanteert, is dat voor gebruikers overzichtelijk.Zet het supportbeleid in de README
Beschrijf het supportbeleid inREADME.md, zodat gebruikers de juiste verwachtingen hebben.
De kosten van het onderhouden van oude versies
Als je oude versies blijft ondersteunen, ontstaan de volgende kosten:- Dubbele bugfixes — dezelfde bug moet je in meerdere branches repareren
- Meer vertakkende code — de complexiteit van conditionele code die verschillende implementaties per versie opvangt
- Uitdijende testmatrix — de CI-doorlooptijd wordt langer
- Complexere securitypatches — je moet ook veilig naar oude versies backporten
De voordelen van vroeg reageren
Als je ondersteuning al klaar is op het moment dat Laravel wordt uitgebracht, kunnen gebruikers meteen naar de nieuwe versie migreren. Dat is een belangrijk signaal van de betrouwbaarheid van je package.Vooraf verifiëren met de ontwikkelversie
Laravel publiceert geen beta’s of RC’s, maar je kunt de volgende versie in ontwikkeling installeren viadev-master of @dev. Door vóór de major-release te verifiëren, is een zero-day-respons mogelijk.
@dev-constraint.
minimum-stability op dev te zetten, kun je de dependencies met ontwikkelversies oplossen.
De eerste stap kan bij alleen een wijziging in composer.json blijven
Zelfs vóór een volledige compatibiliteitscontrole kunnen gebruikers je package al installeren zodra je alleen het dependencybereik incomposer.json bijwerkt en een release uitbrengt.
Releasenieuws bijhouden
Manieren om tijdig op de hoogte te zijn van nieuwe releases.Voorbeeld van een testmatrixconfiguratie
Een voorbeeldworkflow die in GitHub Actions automatisch combinaties van meerdere Laravel- en PHP-versies test.Het belang van fail-fast: false
Metfail-fast: false gaan de tests van de andere combinaties door, ook als één combinatie faalt. Zo zie je in één CI-run bij welke versiecombinatie het probleem optreedt.
De testmatrix stapsgewijs bijwerken
Komt er een nieuwe Laravel-versie uit, dan voeg je die toe aan de matrix. Stop je de ondersteuning van een oude versie, dan verwijder je die uit de matrix.Voorbeeld van composer.json
Een volledig voorbeeld van eencomposer.json die meerdere versies ondersteunt.
Checklist voor versie-upgrades
Vóór de release van de nieuwe Laravel-versie
Vóór de release van de nieuwe Laravel-versie
- Verifieer de werking met de ontwikkelversie (
dev-master/@dev) - Controleer breaking changes in de officiële upgradegids
- Implementeer de ondersteuning voor de nieuwe versie in een testomgeving
- Voeg de nieuwe versie toe aan de testmatrix en controleer in CI
Eerste acties direct na de release
Eerste acties direct na de release
- Voeg de nieuwe versie toe aan de
illuminate/*-vereisten incomposer.json - Werk zo nodig de PHP-vereiste bij
- Werk ook
orchestra/testbenchinrequire-devbij naar de bijbehorende versie - Tag de nieuwe versie en laat die doorstromen naar Packagist
- Werk de versiecompatibiliteitstabel in de README bij
Bij het stopzetten van ondersteuning van een oude versie
Bij het stopzetten van ondersteuning van een oude versie
- Vermeld het einde van de ondersteuning duidelijk in de CHANGELOG/README
- Verwijder de constraint van de oude versie uit
composer.json - Verwijder de oude versie uit de testmatrix
- Ruim de conditionele code voor de oude versie op
Gerelateerde pagina’s
De basis van packageontwikkeling
Uitleg over het ontwikkelen van Laravel-packages met de service provider als kern.
Geavanceerd testen met Pest
Uitleg over het schrijven van packagetests met de Expectation API en datasets van Pest.