Hi devs, I would like to follow up my proposal in [1] regarding how we can more systematically and easily collect breaking changes, so that major release announcements can officially include a list of such changes.
Originally the idea was to collect these in the Wiki whenever a breaking change is merged, but the extra step to go to the Wiki after closing the JIRA ticket seems to be a bit too tedious. There were other suggestions by simply doing this: 1. when closing the ticket, label the JIRA ticket as either `state-compat-breaking` / `api-breaking` / `api-deprecated` 2. leave a comment on the JIRA that describes the change. Ideally, this comment can be directly copy-and-pasted as an announcement for the change. When releasing a major release, for example 1.4, the release manager can then search for such changes by simply filtering the fix version and labels. For `api-breaking` / `api-deprecated` changes, it would be straightforward: public API was broken / deprecated starting from the fix version set on the ticket. For `state-compat-breaking` changes: please describe clearly in the added comment which older versions the state is no longer compatible with. For example, "State compatibility is broken for versions before Flink XX. To restore savepoints prior to Flink XX in the latest release Flink YY, please first restore the savepoint with a version > XX and < YY.” Note that the contracts of `@Public` / `@PublicEvolving` [2] should still remain the same; we’re not discussing altering the API stability contracts here. Also note that the discussion for our state backwards compatibility policy is being discussed here [3]. What do you think? Ideally this would be minimal extra effort for committers, and would make it easier to let our release announcements and API migration guide [4] be much more informative of these changes. If you agree, I'll add this guideline to [5], and suggest that we start doing this immediately starting from Flink 1.4.0. Cheers, Gordon [1] http://apache-flink-mailing-list-archive.1008284.n3.nabble.com/RESULT-VOTE-Release-Apache-Flink-1-3-0-RC3-td17841.html [2] https://cwiki.apache.org/confluence/display/FLINK/Stability+Annotations [3] http://apache-flink-mailing-list-archive.1008284.n3.nabble.com/DISCUSS-Backwards-compatibility-policy-td17640.html [4] https://ci.apache.org/projects/flink/flink-docs-release-1.3/dev/migration.html [5] https://cwiki.apache.org/confluence/display/FLINK/Apache+Flink+development+guidelines
