This is an automated email from the ASF dual-hosted git repository.
chesnay pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/flink.git
The following commit(s) were added to refs/heads/master by this push:
new 030baed8d6e [FLINK-29262][docs] Document API compatibility guarantees
030baed8d6e is described below
commit 030baed8d6e406b83018671d76b817193c258ded
Author: Chesnay Schepler <[email protected]>
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>
