Repository navigation
[Discuss] Support providing hints for breaking changes #817
Description
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 ([Fleet] Detect breaking changes in integration change logs and flag them to users during integration upgrades kibana#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.
Related issues
- Discuss: guidelines for a package with breaking changes #229
- [Fleet] Detect breaking changes in integration change logs and flag them to users during integration upgrades kibana#187481
- Add assistance to detect common backwards compatibilty issues elastic-package#579. In this issue we help preventing breaking changes, but what to do next after detecting a breaking change if the change cannot be avoided?
- Discuss: deprecation path for packages #192 and Allow integration authors to deprecate integrations and data streams #227 contain discussions about deprecations, an special case of breaking changes.
Reacted by Luca Belluccini and Sam Crauwels
Activity
Oddly commentedon Feb 5, 2025
Not sure if this is the right place, but deprecation hints when using elastic-package to build packages would be very welcome for those of us who build our own packages.
jlind23 commentedon Feb 18, 2025
@kpollich @jamiehynds @nimarezainia instead of over engineering this could we imagine an easy solution which would be to display a pop up warning the users whenever there is major version bumped in the package ready to be installed? This would avoid us to implement any flags or any logic in the package spec itself. Any thoughts?
kpollich commentedon Feb 19, 2025
Do we enforce a major version bump in the integration's version when its targeted stack/Kibana version is bumped by a major? I think this could be a simple way to get some of this behavior, but I don't know that we have any kind of enforcement on package maintainers that would guarantee we trigger the pop-up when it's intended.
ebeahan commentedon Feb 19, 2025
The changelog spec includes a
breaking-changetype maintainers should use for any breaking changes.Maybe the upgrade banner includes a warning if a newer changelog entry contains a
breaking-change?kpollich commentedon Feb 25, 2025
I think Eric's suggestion is the best path forward here. We can detect when the upgrade from current version to latest version includes a breaking change by parsing the
changelog.yml. Then we can display a warning in this upgrade callout + the breaking change description as it appears inchangelog.yml.jamiehynds commentedon Mar 18, 2025
Could we take this a step further by not only providing a hint about a breaking change but also requiring users to acknowledge it before proceeding with an update? The need for acknowledgment could be based on the severity of the change, as determined by PM and engineering.
For example, in this case, it would be beneficial to clearly inform users about the impact of the breaking change and require explicit acknowledgment before they update. This approach ensures users are fully aware of the implications and prevents any unexpected disruptions.
jsoriano commentedon Mar 18, 2025
Something like this is proposed in this linked issue: elastic/kibana#187481
kpollich commentedon Mar 25, 2025
Moving this out of our iteration and will flesh out elastic/kibana#187481 with some UX mockups to make it actionable.
efd6 commentedon May 11, 2025
An issue exists with the
changes.typefield in that it makes the implicit claim that breaking-change is orthogonal to both bugfix and enhancement since only one of the three possible options can be used in any given change, but this is not the case; a breaking change is necessarily either a bugfix or an enhancement, so it should be the case that you can set both. Ideally, it would have been a separate boolean field but that horse has already bolted, so it would be good if the type could be relaxed to support an array of string so that they could be treated as tags.jsoriano commentedon May 13, 2025
I remember someone [maybe you? 🤔] suggested once the introduction of a new type like
breaking-bugfix, that would be both a bugfix and a breaking change.breaking-changewould be used then for other changes, like enhancements, that are also breaking changes.efd6 commentedon May 13, 2025
I don't think that was me. It would work, but it seems like a hack to work around the the type system here.