Qinghui Xu created FLINK-39269:
----------------------------------
Summary: Keep doc for deprecated config option
Key: FLINK-39269
URL: https://issues.apache.org/jira/browse/FLINK-39269
Project: Flink
Issue Type: Improvement
Components: Documentation
Reporter: Qinghui Xu
*Context:*
While working on FLINK-21309, I was trying to deprecate a config option while
providing a fallback behavior for it when it's disabled. It turns out the doc
generation will discard the item such that the updated description (behavior
change) is missing for users, which may lead to a miscommunication /
information gap.
*Suggestion:*
Usually deprecated items are not for an immediate removal and will still stay
for a while (at least across a couple of minor versions). For this purpose, the
Java `Deprecated` annotation provides a `forRemoval` flag which is off by
default. We can rely on this flag and drop the item from documention only if
`forRemoval` is on.
* Potential impact of this change: I run a quick test of this change, and it
turns out only one item will reappear in the doc site. This is because for most
of the "deprecated" options, we also annotate them with
`ExcludeFromDocumentation`.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
