Guide de mise à niveau

Le changelog de la release cible constitue le contrat de déploiement. Ne mettez jamais Vavang Invoice à niveau en exécutant les migrations à l’aveugle puis en déduisant leur sécurité après coup.

Avant la mise à niveau

1. Lire l’entrée de la release cible dans le CHANGELOG.md du plugin.
2. Vérifier Breaking changes, Manual actions, Migration compatibility et les notes de rollback.
3. Confirmer que la version cible supporte les versions PHP, Sylius et Sylius InvoicingPlugin déployées.
4. Créer un point de restauration base de données testé.
5. Construire la release applicative cible séparément et exécuter ses tests automatisés.

Mise à niveau standard rolling-compatible

Utilisez ce flux uniquement si la release cible déclare Migration compatibility: rolling-compatible.

composer require vavang/invoice-plugin:<target-version> --no-update
composer update vavang/invoice-plugin --with-all-dependencies --no-interaction
bin/console sylius-invoice:check-requirements

Construisez/mettez en cache la nouvelle release hors du répertoire servi. Appliquez les migrations comme étape dédiée :

bin/console doctrine:migrations:migrate --no-interaction

Puis :

bin/console cache:clear
bin/console sylius-invoice:compliance:doctor

Basculez le trafic via le mécanisme atomique de l’application hôte et redémarrez les workers Messenger longue durée :

bin/console messenger:stop-workers

Le superviseur/orchestrateur doit démarrer les nouveaux consumers de sylius_invoice_async.

Quand une maintenance est requise

Si les notes déclarent maintenance required, suivez exactement la procédure de la release. Les causes typiques sont une migration destructive/incompatible, une transformation obligatoire de configuration, une bascule de protocole fournisseur ou une transformation manuelle de données incompatible avec les écritures de l’ancienne version.

N’élargissez pas la fenêtre de maintenance par convention : interrompez uniquement les chemins nécessaires à l’opération documentée.

Invariant d’historique fiscal

Une mise à niveau doit préserver documents de conformité, claims de traitement des factures source, historiques de transmission/audit et journal métier. Ne corrigez jamais un upgrade en supprimant/recréant les tables du plugin ou en effaçant l’historique fiscal.

Rollback

Après une migration additive/rétrocompatible, le rollback applicatif consiste normalement à revenir au code/workers précédents. N’exécutez pas automatiquement les migrations Doctrine down.

Pour une release comportant des changements de données/schéma non rétrocompatibles, utilisez les instructions de rollback spécifiques et restaurez la base uniquement lorsque c’est explicitement requis.

Ruptures et actions manuelles

Une release avec rupture doit nommer le contrat affecté, le changement application/configuration/migration requis et l’action opérateur. Si ces informations manquent, considérez la documentation de release comme incomplète plutôt que d’inventer le chemin de migration.