My 2 cents: Since we have a migration guide, I think people who hit problems when upgrading Spark will read it. We should mention all the breaking changes there, except for trivial ones like obvious bug fixes. Even if there is no meaningful migration to guide for things like removing a deprecated API, it's still useful to have an item in the migration guide, to explain why we remove it.
Release notes, on the other hand, should include all the major things, like new features, improvements, new APIs, bug fixes, breaking changes, etc., as long as they are major. For example, dropping Scala 2.11 is a major breaking change and should be put in the release notes. That said, we may have some items in both the migration guide and the release notes. Release notes can be read by many people and I think it's better to not make it too verbose. On Tue, Jun 9, 2020 at 10:33 PM Sean Owen <sro...@gmail.com> wrote: > A few different takes surfaced: > > > https://issues.apache.org/jira/browse/SPARK-26043?focusedCommentId=17128908&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#comment-17128908 > > No significant disagreements, just might be worth clarifying a consensus > policy. > > "I feel this is a tiny thing that we should put into the migration guide, > not release notes? ... it depends on the definition of migration guide and > release notes: If I upgrade to 3.0 and hit compiler error, which one should > I read?" > > "I think it's the other way around: some things are worth noting, but > there is no meaningful migration to guide. So they go in release notes, not > a migration guide, if anything. Do we have a different understanding?" > > "Migration guide: legitimate improvements yet that are breaking. If that's > too trivial or minor, I wouldn't document. It depends on a committer's call. > Release note: significant breaking changes including the bug fixes and/or > improvement. One JIRA could appear in both migration guide and release > notes if it's worthwhile." >
