[All integrations documentation] - add a section dedicated to the list of the breaking change / changes / updates

Hi, everybody knows that breaking changes happens often. Today when something doesn’t work on your home assistant you have three solutions :

1 - consult the latest release notes (but in which one you will find the breaking change ? I mean it has been broken with 0.116 , 0.117 or 0.118 ? )
2 - You read again the documentation with the hope to find the difference with your deprecated configuration.
3 - You go directly to github to see what happens to your favorite integration. (warrior way)

Well I think that we could gain a lot of time if the last breaking changes and last little change which impact the way the integration work should be logged in the documentation of the integration.

To be precise it means that an optimization would not be logged (it doesn’t change the way your configure your integration), but a change in the way you can declare the integration would be logged.

What I imagine is a section in the bottom of each integration documentation page which reference the lastest breaking changes (in the same way that it is indicated in each release notes).
There is just the version numbers of HA which are related to a breaking change.
Like in release notes, these are collapsed text block : when you click on the version number you can consult the detail.

Example for the KNX integration documentation :

It would be really great if there is automatic config scanner which looks up the integrations/blocks which are affected by the breaking change, so before version upgrade I would see the list + reference of changes which are actually affecting.

The manual scanning won’t probably work or it would just waste your time and you probably most likely miss some important changes.

2 Likes

Wouldn’t it be possible to browse documentation per release version just like ansible documentation does ? Or maybe a feature to access documentation diff could do the trick.

1 Like

Whilst the sentiments of this post a very valid, there are currently two HACS custom components that I use, firstly Breaking Changes which lists all breaking changes following an update, and secondly but more importantly I use Config Check which when run as a service loads the latest update and runs it against your config. It then reports if your configuration is ok or not. So far I have been able to prevent system breaks by doing a bit of work before the fatal crash.

3 Likes