I’ve been bitten several times by failing to check the Breaking Changes section of the release notes for HomeAssistant before upgrading. This seems a common problem experienced by many. My feature request is to include a link to breaking changes and a comment about this, such as “Note: Please check the list of breaking changes before updating” in the dialog that appears when clicking “Update” on the Supervisor Dashboard page.
It would be even better if HA could progamatically detect if any of your installed addons are affected, however for now I’d settle for simply having a text change with a link to the latest breaking changes.
That’s a great idea, and given that secret knowlege, I can hopefully solve this for myself - but it doesn’t solve it for all the hundreds (thousands) of people who find Home Assistant brittle and frustrating, and are hesitant to upgrade for fear of their house breaking.
The breaking changes should be displayed in the app with a checkbox that says you’ve read them before performing an upgrade.
There is a link to the release notes right next to the upgrade button.
Not reading them is a matter of choice not of opportunity. And no matter how you display them this will never change.
@seanomat That’s a pretty obtuse perspective; if user experience didn’t matter or exist, I might agree, but given that we have a choice about how we want to display breaking changes to the user, wouldn’t it make sense to do so in a way that minimizes suprises and makes it as easy as reasonably possible for a person to know if upgrading is going to break their smart home?
With the release of 2022.4, we now have “update entities”:
If components could expose an attribute, either through an update entity or on their own, then components which had breaking changes could set this flag, and HA users would know if any of the components they have installed would cause a breaking change if upgraded.
Components could also expose a flag for if they support auto-detecting breaking changes. If it wasn’t present or wasn’t set, the UI could easily display “The following components may break if you upgrade:”. This would encourage component developers to implement support, and could be done slowly over time.
Given that Nabu Casa recently hired a UX developer full-time, it’s pretty clear that giving users a good experience is important. I wonder what @matthiasdebaat thinks?
From a user perspective you don’t want to bothered by any breaking changes. That means that a developer has to create a migration script, that takes a lot of extra time or is not even possible. In an open source project like Home Assistant that’s not something we can’t demand from our developers.
The next best option is to tell you what kind of breaking changes specific to you before updating. I don’t know if that is possible though. Adding a checkbox saying you’ve read the breaking changes before upgrading is a bit too much in my opinion. Especially if we list the breaking changes above the update button.
This would improve the experience from our current ‘first’ iteration: listing them in our release notes. There is optionally an add-on or custom component a user can opt-in for that helps but isn’t in the users flow.
I asked for pretty much the same thing two months ago and the general consensus was that it was not needed because it’s so easy to read them yourself.
But I still believe a breaking changes list where your integrations are presented at the top is far better than what it is today.
Since the breaking changes of any release is known, and the integrations used in a installation is known the list can fairly easily be sorted/highlighted to present your integrations at the top.
And if you upgrade past multiple versions the same logic could probably be used to get the breaking changes from each version.
Upgrading from 2021 something to the current version is a challenge if you need to read all the breaking changes.
Looking at analytics page there seems to be 850 installs that still run on 2021.4, that is 12 breaking changes list these people have to read through before updating.
Thanks for the reply @matthiasdebaat and @Hellis81 – I agree that providing migration infrastructure is overkill and probably fraught with problems.
For me, having metadata associated with addon/component releases be visible at upgrade time would be enough for me and probably enough for others to prevent a lot of heartache. I’ve skipped months of updates because I didn’t want to deal with having to roll back / fix anything, should it go wrong, even after skimming breaking changes release notes. So, anything in this area would go a long way.
Some low-hanging fruit for possible solutions:
Add component/addon metadata for “breaking changes” (“breaking changes in this release”) which is displayed below each component before doing an upgrade
Check to see if any addon/component that is being upgraded has a value in this field, and if so, display a single confirmation/checkbox with a message, “It looks like you have one or more addons/components that will break during this upgrade. Are you sure you want to upgrade?” Clicking the checkbox would enable the Upgrade button.
It would be important for the metadata to be optional, so as not to disrupt the developer or user experience when updating an addon/component where the developer has not provided information about if their update does or does not include a breaking change. I imagine a boolean flag for “has breaking change” and a text string, and maybe a url for link to the release notes for that specific addon.
If an addon/component was being upgraded that did not provide this info, a message could be displayed, “We can’t tell if one or more addons/components you’re upgrading will cause a problem, so please check the release notes” (linked). I imagine addon providers could also get analytics about how people users saw these messages, which would provide some motivation to provide it in future releases.
Just because a component you’re using has a breaking change doesn’t necessarily mean your instance will break. There’s a lot of ifs there:
Am I actually using the feature(s) of this integration which are affected by this breaking change?
Is it a breaking change now or is it a deprecation informing me I have several months to fix my config before something really breaks?
Is the impact important enough to me to do anything about it? I may display a piece of diagnostic data on my dashboard currently but if I’ve never looked at it I don’t care if it goes.
This kind of messaging makes it seem like every breaking change is a five alarm fire. In reality as someone who reviews the release notes for every release my integrations have been in there many many more times then the number of times I’ve actually had to do something about it to upgrade.
But I do agree that it would be nice if there was a way to see a filtered view of that section of the blog post based on the integrations I actually use in my HA. I only care about the ones I use and occasionally have missed a breaking change for an integration I use when skimming the list.
As for addons, not sure which addons you’re using but I’ve rarely had an issue with long changelogs in addons. They’re usually a couple lines. I feel like creating a system to highlight the occasional breaking change when the entire changelog is usually a few lines is overkill. Between dev time of this feature and adoption time in all addons you’re looking at a lot of work to occaisionally highlight one line out of a 3-5 line changelog. I feel like there are better uses of this time.
Also just an FYI a lot of users seem to use the “auto-update” option for addons. This feature automatically installs the next update as soon as it is available, regardless of its content and without giving the sys admin any warning or chance to review potential breaking changes. Which means if an addon does have breaking changes that affect the install the user will see their system break and then rollback. Despite this, it appears to be heavily used (from my perspective, there’s no analytics on this so extrapolating from issues, posts, etc).
So while I personally completely agree with your strategy here I should note that a lot of users don’t it seems. They would prefer to keep quickly moving forward at the cost of the occasional rollback.