You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@flink.apache.org by Ted Yu <yu...@gmail.com> on 2017/07/06 10:35:15 UTC
Re: [DISCUSS] Managing announcements of breaking API / state
compatibility changes in major releases
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 <al...@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 <tz...@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
Re: [DISCUSS] Managing announcements of breaking API / state
compatibility changes in major releases
Posted by "Tzu-Li (Gordon) Tai" <tz...@apache.org>.
Alright, it seems like there is no objections on this.
I’ll proceed to update the development guidelines on the Flink Wiki [1] for this.
Ideally, this should also go into Flink’s committer guidelines (when we eventually have one []) since it would be most relevant for committers after they merge PRs and close JIRAs.
Cheers,
Gordon
[1] https://issues.apache.org/jira/browse/FLINK-6771
On 6 July 2017 at 10:09:33 PM, Tzu-Li (Gordon) Tai (tzulitai@apache.org) wrote:
@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 (yuzhihong@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 <al...@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 <tz...@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
Re: [DISCUSS] Managing announcements of breaking API / state
compatibility changes in major releases
Posted by "Tzu-Li (Gordon) Tai" <tz...@apache.org>.
@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 (yuzhihong@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 <al...@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 <tz...@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