JingGe commented on code in PR #23865:
URL: https://github.com/apache/flink/pull/23865#discussion_r1413472466
##########
docs/content/docs/ops/upgrading.md:
##########
@@ -60,6 +60,32 @@ Code written against a `PublicEvolving` API in 1.15.2 will
continue to run in 1.
That same code would have to be recompiled when upgrading to 1.16.0 though.
{{< /hint >}}
+### Deprecated API Migration Period
+When an API is deprecated, it is marked with the `@Deprecated` annotation and
a deprecation message is added to the Javadoc.
+According to
[FLIP-321](https://cwiki.apache.org/confluence/display/FLINK/FLIP-321%3A+Introduce+an+API+deprecation+process),
+starting from release 1.18, each deprecated API will have a guaranteed
migration period depending on the API stability level:
+
+| Annotation | Guaranteed Migration Period |
+|:----------------:|:----------------------------------------------:|
+| `Public` | 2 minor releases |
+| `PublicEvolving` | 1 minor release |
+| `Experimental` | 1 patch release for the affected minor release |
+
+The source code of a deprecated API will be kept for at least the guaranteed
migration period,
+and may be removed at any point after the migration period has passed.
+
+{{< hint info >}}
+{{< label Example >}}
+Assuming a release sequence of 1.18, 1.19, 1.20, 2.0, 2.1, ..., 3.0,
+- if a `Public` API is deprecated in 1.18, it will not be removed until 2.0.
+- if a `Public` API is deprecated in 1.20, the source code will be kept in 2.0
because the migration period is 2 minor releases. This means the source code
will be removed in 3.0 at the earliest.
Review Comment:
Although the source compatibility described in `API compatibility
guarantees` implicitly said that a `Public` API can only be removed after one
major release, it would be easier for us to follow the deprecation rule
described in this section(i.e. don't make readers think), if we could
explicitly point out that, in this case, for the `Public` API deprecated in
1.20 and carried over to 2.0, even after 2 minor releases, i.e. 2.0 and 2.1, it
still can not be removed in 2.2 and can only be removed in 3.0 at the earliest.
WDYT?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscr...@flink.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
