This is an automated email from the ASF dual-hosted git repository. chesnay pushed a commit to branch release-1.15 in repository https://gitbox.apache.org/repos/asf/flink.git
The following commit(s) were added to refs/heads/release-1.15 by this push: new 1afcba0c61c [FLINK-29262][docs] Document API compatibility guarantees 1afcba0c61c is described below commit 1afcba0c61cdc654554b91ca1f47646c540850bf Author: Chesnay Schepler <ches...@apache.org> AuthorDate: Tue Sep 13 20:51:24 2022 +0200 [FLINK-29262][docs] Document API compatibility guarantees --- docs/content.zh/docs/ops/upgrading.md | 30 ++++++++++++++++++++++++++++++ docs/content/docs/ops/upgrading.md | 30 ++++++++++++++++++++++++++++++ docs/layouts/shortcodes/check.html | 21 +++++++++++++++++++++ docs/layouts/shortcodes/xmark.html | 21 +++++++++++++++++++++ 4 files changed, 102 insertions(+) diff --git a/docs/content.zh/docs/ops/upgrading.md b/docs/content.zh/docs/ops/upgrading.md index ba8aa3bc142..0fca75d0e8d 100644 --- a/docs/content.zh/docs/ops/upgrading.md +++ b/docs/content.zh/docs/ops/upgrading.md @@ -30,6 +30,36 @@ Flink DataStream programs are typically designed to run for long periods of time This document describes how to update a Flink streaming application and how to migrate a running streaming application to a different Flink cluster. +## API compatibility guarantees + +The classes & methods of the Java/Scala APIs that are intended for users are annotated with the following stability annotations: +* `Public` +* `PublicEvolving` +* `Experimental` + +{{< hint info>}} +Annotations on a class also apply to all members of that class, unless otherwise annotated. +{{< /hint >}} + +Any API without such an annotation is considered internal to Flink, with no guarantees being provided. + +An API that is `source` compatible means that code **written** against the API will continue to **compile** against a later version. +An API that is `binary` compatible means that code **compiled** against the API will continue to **run** against a later version. + +This table lists the `source` / `binary` compatibility guarantees for each annotation when upgrading to a particular release: + +| Annotation | Major release<br>(Source / Binary) | Minor release<br>(Source / Binary) | Patch release<br>(Source / Binary) | +|:----------------:|:----------------------------------:|:----------------------------------:|:----------------------------------:| +| `Public` | {{< xmark >}}/{{< xmark >}} | {{< check >}}/{{< xmark >}} | {{< check >}}/{{< check >}} | +| `PublicEvolving` | {{< xmark >}}/{{< xmark >}} | {{< xmark >}}/{{< xmark >}} | {{< check >}}/{{< check >}} | +| `Experimental` | {{< xmark >}}/{{< xmark >}} | {{< xmark >}}/{{< xmark >}} | {{< xmark >}}/{{< xmark >}} | + +{{< hint info >}} +{{< label Example >}} +Code written against a `PublicEvolving` API in 1.15.2 will continue to run in 1.15.3, without having to recompile the code. +That same code would have to be recompiled when upgrading to 1.16.0 though. +{{< /hint >}} + ## Restarting Streaming Applications The line of action for upgrading a streaming application or migrating an application to a different cluster is based on Flink's [Savepoint]({{< ref "docs/ops/state/savepoints" >}}) feature. A savepoint is a consistent snapshot of the state of an application at a specific point in time. diff --git a/docs/content/docs/ops/upgrading.md b/docs/content/docs/ops/upgrading.md index 4dd76928b30..d14a03b0d94 100644 --- a/docs/content/docs/ops/upgrading.md +++ b/docs/content/docs/ops/upgrading.md @@ -30,6 +30,36 @@ Flink DataStream programs are typically designed to run for long periods of time This document describes how to update a Flink streaming application and how to migrate a running streaming application to a different Flink cluster. +## API compatibility guarantees + +The classes & members of the Java/Scala APIs that are intended for users are annotated with the following stability annotations: +* `Public` +* `PublicEvolving` +* `Experimental` + +{{< hint info>}} +Annotations on a class also apply to all members of that class, unless otherwise annotated. +{{< /hint >}} + +Any API without such an annotation is considered internal to Flink, with no guarantees being provided. + +An API that is `source` compatible means that code **written** against the API will continue to **compile** against a later version. +An API that is `binary` compatible means that code **compiled** against the API will continue to **run** against a later version. + +This table lists the `source` / `binary` compatibility guarantees for each annotation when upgrading to a particular release: + +| Annotation | Major release<br>(Source / Binary) | Minor release<br>(Source / Binary) | Patch release<br>(Source / Binary) | +|:----------------:|:----------------------------------:|:----------------------------------:|:----------------------------------:| +| `Public` | {{< xmark >}}/{{< xmark >}} | {{< check >}}/{{< xmark >}} | {{< check >}}/{{< check >}} | +| `PublicEvolving` | {{< xmark >}}/{{< xmark >}} | {{< xmark >}}/{{< xmark >}} | {{< check >}}/{{< check >}} | +| `Experimental` | {{< xmark >}}/{{< xmark >}} | {{< xmark >}}/{{< xmark >}} | {{< xmark >}}/{{< xmark >}} | + +{{< hint info >}} +{{< label Example >}} +Code written against a `PublicEvolving` API in 1.15.2 will continue to run in 1.15.3, without having to recompile the code. +That same code would have to be recompiled when upgrading to 1.16.0 though. +{{< /hint >}} + ## Restarting Streaming Applications The line of action for upgrading a streaming application or migrating an application to a different cluster is based on Flink's [Savepoint]({{< ref "docs/ops/state/savepoints" >}}) feature. A savepoint is a consistent snapshot of the state of an application at a specific point in time. diff --git a/docs/layouts/shortcodes/check.html b/docs/layouts/shortcodes/check.html new file mode 100644 index 00000000000..c3670e808cc --- /dev/null +++ b/docs/layouts/shortcodes/check.html @@ -0,0 +1,21 @@ +{{/* +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +*/}}{{/* +Adds a check icon. +*/}} +<i class="fa fa-solid fa-check" style="color:green"></i> diff --git a/docs/layouts/shortcodes/xmark.html b/docs/layouts/shortcodes/xmark.html new file mode 100644 index 00000000000..5855419e351 --- /dev/null +++ b/docs/layouts/shortcodes/xmark.html @@ -0,0 +1,21 @@ +{{/* +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +*/}}{{/* +Adds a X mark icon. +*/}} +<i class="fa fa-solid fa-times" style="color:darkred"></i>