[pancsta]

Not related really, as you can (and should) publish BREAKING.md separately. Release notes should inform more about new stuff than the update process. Usually PRs have details, so release notes can be easily automated. Migrations, on the other hand…

[dustfinger]

+1 on separating "how to upgrade" due to breaking changes from "what’s new". A dedicated BREAKING.md / MIGRATIONS.md is a really good idea.

One thing I am trying to do is make the generator surface breaking/migration items explicitly, but I still think anything that requires human judgment (migration steps, caveats) should be hand-curated in a dedicated document like you suggested.