Release notes and the release party

Every release comes with release notes: a blog post on home-assistant.io that explains what is new, what changed, and what people need to do. For many people, it is the only thing they read about a release. Getting it right matters.

The release notes follow the same structure every month:

• An introduction with the highlights, and the recording of the release party at the top.
• The big features, each with its own section, screenshots, and often a short video.
• Integrations: new integrations, noteworthy improvements, integrations that reached a new level of the quality scale, integrations that can now be set up from the UI, and integrations that were removed.
• Other noteworthy changes: smaller features worth knowing about.
• Patch releases: added during the month, with the fixes of each patch release.
• Need help? Join the community: where to get help, and where to report issues.
• Backward-incompatible changes: every backward-incompatible change, grouped per integration, and a list of developer blog posts that matter for custom integration developers.
• All changes: a link to the full changelog.

The full changelog lists every merged pull request of the release, with its author. It is generated by the release team with the release helper scripts.

The release notes are written by the release team, with help from others. The people who helped are thanked by name at the top of every release post. Writing the release notes is not a public free-for-all, but you can help in several ways.

• Write a good pull request description. The release notes authors read pull requests to understand a feature. A clear description, with a screenshot of what changed, saves them a lot of time.
• Write a good backward-incompatible change section. It is copied into the release notes almost as is. See Document a backward-incompatible change.
• Get your documentation in on time. A feature without documentation is hard to write about, and hard to link to. Open the documentation pull request against the next branch of home-assistant.io, together with the code. See Writing docs.
• Review the beta release notes. During the beta week, the release notes are already published at rc.home-assistant.io. Spot a mistake, a broken link, or something unclear? Report it in the #beta channel on Discord, or open an issue or pull request on home-assistant.io.

On release day, there is a release party: a live stream on the Home Assistant YouTube channel. The Home Assistant and Community teams of the Open Home Foundation put it together. They walk through what is new and show the features in action. Sometimes guests join to talk about something they worked on.

The recording is embedded at the top of the release notes afterward, so you can watch it later.

Patch releases do not get their own blog post. Their changes are added to the release notes of that month, under Patch releases, with the date and the list of fixes.