flink-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Tzu-Li (Gordon) Tai" <tzuli...@apache.org>
Subject [DISCUSS] Managing announcements of breaking API / state compatibility changes in major releases
Date Thu, 06 Jul 2017 07:59:44 GMT

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.


[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

  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message