tillrohrmann closed pull request #7132: [BP-1.5][FLINK-10880] Exclude
JobManagerOptions#EXECUTION_FAILOVER_STRATEGY from documentation
URL: https://github.com/apache/flink/pull/7132
This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:
As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):
diff --git a/docs/_includes/generated/job_manager_configuration.html
b/docs/_includes/generated/job_manager_configuration.html
index db0ca53614b..774667407a1 100644
--- a/docs/_includes/generated/job_manager_configuration.html
+++ b/docs/_includes/generated/job_manager_configuration.html
@@ -17,11 +17,6 @@
<td style="word-wrap: break-word;">16</td>
<td>The maximum number of prior execution attempts kept in
history.</td>
</tr>
- <tr>
- <td><h5>jobmanager.execution.failover-strategy</h5></td>
- <td style="word-wrap: break-word;">"full"</td>
- <td>The maximum number of prior execution attempts kept in
history.</td>
- </tr>
<tr>
<td><h5>jobmanager.heap.mb</h5></td>
<td style="word-wrap: break-word;">1024</td>
diff --git a/docs/release-notes/flink-1.5.md b/docs/release-notes/flink-1.5.md
index ba377dd85b9..666f6538025 100644
--- a/docs/release-notes/flink-1.5.md
+++ b/docs/release-notes/flink-1.5.md
@@ -96,5 +96,13 @@ The Kinesis dependencies of Flink’s Kinesis connector have
been updated to the
<aws.kinesis-kpl.version>0.12.9</aws.kinesis-kcl.version>
```
+<!-- Remove once FLINK-10712 has been fixed -->
+### Limitations of failover strategies
+Flink's non-default failover strategies are still a very experimental feature
which come with a set of limitations.
+You should only use this feature if you are executing a stateless streaming
job.
+In any other cases, it is highly recommended to remove the config option
`jobmanager.execution.failover-strategy` from your `flink-conf.yaml` or set it
to `"full"`.
+
+In order to avoid future problems, this feature has been removed from the
documentation until it will be fixed.
+See [FLINK-10880](https://issues.apache.org/jira/browse/FLINK-10880) for more
details.
{% top %}
diff --git
a/flink-annotations/src/main/java/org/apache/flink/annotation/docs/Documentation.java
b/flink-annotations/src/main/java/org/apache/flink/annotation/docs/Documentation.java
index 4e424c76cf8..d5e12684566 100644
---
a/flink-annotations/src/main/java/org/apache/flink/annotation/docs/Documentation.java
+++
b/flink-annotations/src/main/java/org/apache/flink/annotation/docs/Documentation.java
@@ -40,6 +40,19 @@
String value();
}
+ /**
+ * Annotation used on config option fields to exclude the config option
from documentation.
+ */
+ @Target(ElementType.FIELD)
+ @Retention(RetentionPolicy.RUNTIME)
+ @Internal
+ public @interface ExcludeFromDocumentation {
+ /**
+ * The optional reason why the config option is excluded from
documentation.
+ */
+ String value() default "";
+ }
+
private Documentation(){
}
}
diff --git
a/flink-core/src/main/java/org/apache/flink/configuration/JobManagerOptions.java
b/flink-core/src/main/java/org/apache/flink/configuration/JobManagerOptions.java
index add8e68c26d..a0f479f14fb 100644
---
a/flink-core/src/main/java/org/apache/flink/configuration/JobManagerOptions.java
+++
b/flink-core/src/main/java/org/apache/flink/configuration/JobManagerOptions.java
@@ -19,6 +19,7 @@
package org.apache.flink.configuration;
import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.annotation.docs.Documentation;
import static org.apache.flink.configuration.ConfigOptions.key;
@@ -92,6 +93,7 @@
/**
* The maximum number of prior execution attempts kept in history.
*/
+ @Documentation.ExcludeFromDocumentation("The failover strategy feature
is highly experimental.")
public static final ConfigOption<String> EXECUTION_FAILOVER_STRATEGY =
key("jobmanager.execution.failover-strategy")
.defaultValue("full")
diff --git
a/flink-docs/src/main/java/org/apache/flink/docs/configuration/ConfigOptionsDocGenerator.java
b/flink-docs/src/main/java/org/apache/flink/docs/configuration/ConfigOptionsDocGenerator.java
index b73a40e7c04..a9cebd607de 100644
---
a/flink-docs/src/main/java/org/apache/flink/docs/configuration/ConfigOptionsDocGenerator.java
+++
b/flink-docs/src/main/java/org/apache/flink/docs/configuration/ConfigOptionsDocGenerator.java
@@ -148,7 +148,7 @@ static void processConfigOptions(String rootDir, String
module, String packageNa
List<OptionWithMetaInfo> configOptions = new
ArrayList<>(8);
Field[] fields = clazz.getFields();
for (Field field : fields) {
- if (field.getType().equals(ConfigOption.class)
&& field.getAnnotation(Deprecated.class) == null) {
+ if (isConfigOption(field) &&
shouldBeDocumented(field)) {
configOptions.add(new
OptionWithMetaInfo((ConfigOption<?>) field.get(null), field));
}
}
@@ -159,6 +159,15 @@ static void processConfigOptions(String rootDir, String
module, String packageNa
}
}
+ private static boolean isConfigOption(Field field) {
+ return field.getType().equals(ConfigOption.class);
+ }
+
+ private static boolean shouldBeDocumented(Field field) {
+ return field.getAnnotation(Deprecated.class) == null &&
+
field.getAnnotation(Documentation.ExcludeFromDocumentation.class) == null;
+ }
+
/**
* Transforms this configuration group into HTML formatted table.
* Options are sorted alphabetically by key.
diff --git
a/flink-docs/src/test/java/org/apache/flink/docs/configuration/ConfigOptionsDocGeneratorTest.java
b/flink-docs/src/test/java/org/apache/flink/docs/configuration/ConfigOptionsDocGeneratorTest.java
index 4176c5d65f6..7306e4d7208 100644
---
a/flink-docs/src/test/java/org/apache/flink/docs/configuration/ConfigOptionsDocGeneratorTest.java
+++
b/flink-docs/src/test/java/org/apache/flink/docs/configuration/ConfigOptionsDocGeneratorTest.java
@@ -215,4 +215,44 @@ public void testOverrideDefault() {
assertEquals(expectedTable, htmlTable);
}
+ static class TestConfigGroupWithExclusion {
+ public static ConfigOption<Integer> firstOption = ConfigOptions
+ .key("first.option.a")
+ .defaultValue(2)
+ .withDescription("This is example description for the
first option.");
+
+ @Documentation.ExcludeFromDocumentation
+ public static ConfigOption<String> excludedOption =
ConfigOptions
+ .key("excluded.option.a")
+ .noDefaultValue()
+ .withDescription("This should not be documented.");
+ }
+
+ /**
+ * Tests that {@link ConfigOption} annotated with {@link
Documentation.ExcludeFromDocumentation}
+ * are not documented.
+ */
+ @Test
+ public void testConfigOptionExclusion() {
+ final String expectedTable =
+ "<table class=\"table table-bordered\">\n" +
+ " <thead>\n" +
+ " <tr>\n" +
+ " <th class=\"text-left\"
style=\"width: 20%\">Key</th>\n" +
+ " <th class=\"text-left\"
style=\"width: 15%\">Default</th>\n" +
+ " <th class=\"text-left\"
style=\"width: 65%\">Description</th>\n" +
+ " </tr>\n" +
+ " </thead>\n" +
+ " <tbody>\n" +
+ " <tr>\n" +
+ "
<td><h5>first.option.a</h5></td>\n" +
+ " <td style=\"word-wrap:
break-word;\">2</td>\n" +
+ " <td>This is example description
for the first option.</td>\n" +
+ " </tr>\n" +
+ " </tbody>\n" +
+ "</table>\n";
+ final String htmlTable =
ConfigOptionsDocGenerator.generateTablesForClass(TestConfigGroupWithExclusion.class).get(0).f1;
+
+ assertEquals(expectedTable, htmlTable);
+ }
}
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
With regards,
Apache Git Services
