Upgrade guide
The target release changelog is the deployment contract. Never upgrade Vavang Invoice by running migrations blindly and inferring safety afterward.
Before the upgrade
- Read the target release entry in the plugin
CHANGELOG.md. - Check Breaking changes, Manual actions, Migration compatibility and rollback notes.
- Confirm the target version supports the deployed PHP, Sylius and Sylius InvoicingPlugin versions.
- Create a tested database restore point.
- Build the target application release separately and run its automated tests.
Standard rolling-compatible upgrade
Use this flow only when the target release says 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
Build/cache the new release outside the live serving directory. Apply database migrations as a dedicated deployment step:
bin/console doctrine:migrations:migrate --no-interaction
Then:
bin/console cache:clear
bin/console sylius-invoice:compliance:doctor
Switch traffic using the host application's atomic deployment mechanism and restart long-running Messenger workers:
bin/console messenger:stop-workers
The process supervisor/orchestrator must start replacement consumers for sylius_invoice_async.
When maintenance is required
If release notes say maintenance required, follow the exact release-specific procedure. Typical reasons include destructive/incompatible schema changes, mandatory configuration transformations, provider protocol cutovers or manual data transformations that cannot coexist with writes from the old application.
Do not widen the maintenance window by convention: stop only the paths required by the documented operation.
Fiscal-history invariant
An upgrade must preserve compliance documents, source invoice processing claims, transmission/audit history and business-journal records. Never repair an upgrade by dropping/recreating plugin tables or clearing fiscal history.
Rollback
For an additive/backward-compatible migration, application rollback normally means switching traffic/workers back to the previous code. Do not automatically run Doctrine down migrations.
For a release with non-backward-compatible data/schema changes, use the release-specific rollback instructions and restore the database only when explicitly required.
Breaking changes and manual actions
A release with a breaking change must name the affected contract, the required application/configuration/migration change and the operator action. If these fields are missing, treat the release documentation as incomplete rather than guessing the migration path.