Standardize changelog for integrations

[dgomes]

Problem Statement

Whenever we have broken changes in integrations users fail to realise such and just get a bunch of errors in the logs simply because they skipped reading the breaking changes section of the release blog post.

Solution

manifest.json is read before we load an integration, so we can leverage that in order to detect a broken change before it actually... breaks

I propose we update manifest.json to have a dict with:

{
  "domain": "your_domain_name",
  "name": "Your Integration",
  "documentation": "https://www.example.com",
  "dependencies": [],
  "codeowners": [],
  "requirements": [],
  "breaking_changes": {
    ha_release: "breaking change description",
  }
}

Upon HA upgrade, components with a breaking change trigger a persistent notification and do not actually load, giving users a chance to fix their configurations.

[awarecan]

manifest.json should not include change log. I propose create a separate changelogs.md file per integration, and not limit to breaking changes, but all changes.

I also don't like auto-disable the component, how did system know user hasn't fix the break already? In my opinion, the personalized release note should be just display the release note in a way to highlight the integration user is using. It doesn't need manifest support, the basic element already exist in current version. system_health component to list all using component, we just need a script to decorate release note blog base on system_health component list.

[balloob]

Oh I like @awarecan's idea even more.

I suggest that if we add a changelog, we should write it in machine understandable language, so that we can automatically parse it for the release notes and show in the UI.

Preferably I want the changelog text to be in Markdown, so that we can emphasize and link important parts.

JSON sucks for Markdown, or any multiline text, so probably have a changelog.yaml ? I do think that we should focus on MVP, lots of possibilities, but let's focus on the bare minimum that can help us generate better release notes.

First format that comes to mind:

domain: mqtt
changelog:
- release: 0.92
  author: "@balloob"
  breaking_change: true
  change: >
    The internal MQTT broker has been moved out of the `mqtt` integration and is now part of a new `mqtt_broker` integration. To set it up, update your configuration as follows:

    ```yaml
    mqtt_broker:
      password: bla

    mqtt:
      host: localhost
      username: homeassistant
      password: bla
    ```

[balloob]

And it's good to keep this outside of manifest.json, because manifests are kept in memory while Home Assistant is running, and so should be limited to things that are needed for Home Assistant to run.

[dgomes]

maybe the minimum supported HA version should stay in manifest ?

[balloob]

Let's discuss min supported version in another issue.

[rytilahti]

How about extracting the changelog information from the PRs? We already have tags per integration, so querying those should be fairly straightforward. This will require enforcing user-readable titles & descriptions for the PRs (maybe even adding a new "human-readable description" entry to the template, to be parsed out?).

[balloob]

I think that it's too error prone, we should instead ask people making PRs to also update the changelog for that integration.

[awarecan]

Agree, this should be a user facing document, not git log

[rytilahti]

I don't mean git log here, but a separate new field in the PR template (which can be parsed out for changelogs when making a release). How I see it, this would avoid the need to duplicate the information to different places (no need to poke users forgetting to update the changelogs separately, ..), as the PR should already contain a sane description in cases where it is relevant to end users. Another plus side on this is that each changelog entry can be directly linked back to the PR for those who are interested in more details.

[balloob]

We still need to parse it out and store that data somewhere

[dgomes]

I like the idea of having a field linked to the PR of the change

[awarecan]

I suggest tag it to 1.0 milestone