@Ted Good idea. Using the “Release Note” field would definitely be better than some dangling comment.
On 6 July 2017 at 6:35:24 PM, Ted Yu (yuzhih...@gmail.com) wrote: Thru INFRA-14519, Release Note field has been added to JIRA. We can use this field to record API/ compatibility changes. -------- Original message --------From: Aljoscha Krettek <aljos...@apache.org> Date: 7/6/17 2:01 AM (GMT-08:00) To: dev@flink.apache.org Subject: Re: [DISCUSS] Managing announcements of breaking API / state compatibility changes in major releases +1 This sounds very good! I just hope that everyone is aware enough and doesn’t forget adding these tags. > On 6. Jul 2017, at 09:59, Tzu-Li (Gordon) Tai <tzuli...@apache.org> wrote: > > > 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
