There are situations where breaking changes may be unavoidable. Currently packages can indicate this in changelogs and/or bumping their major versions, but from a user perspective upgrading to versions with breaking changes looks the same as any other upgrade. After the upgrade they may be missing fields or having other kinds of issues.
It should be possible to include hints in packages to handle breaking changes. There can be two kinds of hints:
Hints for Fleet, in case it can do anything during the upgrade.
Hints for users, in case they need to be aware of some change or perform some manual action.
These hints should help with the migration path to versions with breaking changes.
There are some places where the hints could appear:
In breaking change notes in the changelog, a new field could be added with additional information. We should ensure that breaking changes are displayed to users in the UI when upgrading (https://github.com/elastic/kibana/issues/187481), and if possible also in API responses.
In field definitions, we could keep definitions of removed fields, along with additional information to indicate if it was completely removed, moved or whatsoever.
In READMEs we could also add some notes, but this can be difficult to enforce and users may not read it.
We should also assess frequent reasons for breaking changes.
Try to find opportunities to improve the situation here.
There are situations where breaking changes may be unavoidable. Currently packages can indicate this in changelogs and/or bumping their major versions, but from a user perspective upgrading to versions with breaking changes looks the same as any other upgrade. After the upgrade they may be missing fields or having other kinds of issues.
It should be possible to include hints in packages to handle breaking changes. There can be two kinds of hints:
These hints should help with the migration path to versions with breaking changes.
There are some places where the hints could appear:
We should also assess frequent reasons for breaking changes.
Try to find opportunities to improve the situation here.
Related issues