Changelog, deprecations and migrations

The plugin CHANGELOG.md is an operational release contract, not only a feature list.

Required release entry

Every published version must state:

• functional additions/fixes relevant to operators and integrators;
• supported PHP/Sylius/Sylius InvoicingPlugin compatibility;
• Breaking changes — None or the explicit list;
• Manual actions — None or exact operator steps;
• Migration compatibility — rolling-compatible or maintenance required;
• rollback notes when rolling compatibility is not sufficient;
• known limitations when they affect safe adoption.

Deprecations

A deprecation entry must identify:

1. the deprecated contract;
2. the supported replacement;
3. when removal is expected, when known;
4. any migration/action integrators can perform before removal.

Do not remove a documented extension point silently.

Doctrine migrations

Schema migrations are forward migrations by default. They must preserve fiscal/compliance history and be designed with the release's declared rollout compatibility.

A migration that requires a maintenance window or a data transformation must be paired with exact release-note instructions. A Doctrine down migration is not an automatic rollback strategy for production fiscal data.

Compatibility changes

Changing package constraints is release-significant even when application code does not change. A support-range change must update:

• plugin composer.json;
• CI/clean-install matrix;
• changelog compatibility section;
• public compatibility documentation.

Publication gate

Before publishing a version/tag, the release entry must be finalized and the release, tag and external clean-install gates must be green. A tag must not be promoted with placeholder breaking-change or migration information.