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 <[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 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>
