You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@flink.apache.org by ch...@apache.org on 2022/09/13 18:52:01 UTC
[flink] branch release-1.16 updated: [FLINK-29262][docs] Document API compatibility guarantees
This is an automated email from the ASF dual-hosted git repository.
chesnay pushed a commit to branch release-1.16
in repository https://gitbox.apache.org/repos/asf/flink.git
The following commit(s) were added to refs/heads/release-1.16 by this push:
new a325214cd0b [FLINK-29262][docs] Document API compatibility guarantees
a325214cd0b is described below
commit a325214cd0b47b286dad40b788488533799a6da5
Author: Chesnay Schepler <ch...@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 c9dff9e9d30..2fcca451d89 100644
--- a/docs/content.zh/docs/ops/upgrading.md
+++ b/docs/content.zh/docs/ops/upgrading.md
@@ -30,6 +30,36 @@ Flink DataStream 程序通常设计为长时间运行，例如数周、数月甚
本文档介绍了如何更新 Flink 流式应用程序以及如何将正在运行的流式应用程序迁移到不同的 Flink 集群。
+## 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 >}}
+
## 重启流式应用程序
升级流式应用程序或将应用程序迁移到不同集群的操作线基于 Flink 的 [Savepoint]({{< ref "docs/ops/state/savepoints" >}}) 功能。Savepoint 是应用程序在特定时间点的状态的一致快照。
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>