klion26 commented on a change in pull request #247: URL: https://github.com/apache/flink-web/pull/247#discussion_r429771409
########## File path: contributing/code-style-and-quality-components.zh.md ########## @@ -48,96 +48,95 @@ How to name config keys: } ``` -* The resulting config keys should hence be: +* 因此生成的配置键应该： - **NOT** `"taskmanager.detailed.network.metrics"` + **不是** `"taskmanager.detailed.network.metrics"` - **But rather** `"taskmanager.network.detailed-metrics"` + **而是** `"taskmanager.network.detailed-metrics"` -### Connectors +### 连接器 -Connectors are historically hard to implement and need to deal with many aspects of threading, concurrency, and checkpointing. +连接器历来很难实现，需要处理多线程、并发和检查点的许多方面。 -As part of [FLIP-27](https://cwiki.apache.org/confluence/display/FLINK/FLIP-27%3A+Refactor+Source+Interface) we are working on making this much simpler for sources. New sources should not have to deal with any aspect of concurrency/threading and checkpointing any more. +作为 [FLIP-27](https://cwiki.apache.org/confluence/display/FLINK/FLIP-27%3A+Refactor+Source+Interface) 的一部分，我们正在努力让这些源（source）更加简单。新的源应该不必处理并发/线程和检查点的任何方面。 -A similar FLIP can be expected for sinks in the near future. +预计在不久的将来，会有类似针对 sink 的 FLIP。 -### Examples +### 示例 -Examples should be self-contained and not require systems other than Flink to run. Except for examples that show how to use specific connectors, like the Kafka connector. Sources/sinks that are ok to use are `StreamExecutionEnvironment.socketTextStream`, which should not be used in production but is quite handy for exploring how things work, and file-based sources/sinks. (For streaming, there is the continuous file source) +示例应该是自包含的，不需要运行 Flink 以外的系统。除了显示如何使用具体的连接器的示例，比如 Kafka 连接器。源/接收器可以使用 `StreamExecutionEnvironment.socketTextStream`，这个不应该在生产中使用，但对于研究示例如何运行是相当方便的，以及基于文件的源/接收器。（对于流，有连续的文件源） +示例也不应该是纯粹的玩具示例，而是在现实世界的代码和纯粹的抽象示例之间取得平衡。WordCount 示例到现在已经很久了，但它是一个很好的功能突出并可以做有用事情的简单代码示例。 -Examples should also not be pure toy-examples but strike a balance between real-world code and purely abstract examples. The WordCount example is quite long in the tooth by now but it’s a good showcase of simple code that highlights functionality and can do useful things. +示例中应该有不少的注释。他们可以在类级 Javadoc 中描述示例的总体思路，并且描述正在发生什么和整个代码里使用了什么功能。还应描述预期的输入数据和输出数据。 -Examples should also be heavy in comments. They should describe the general idea of the example in the class-level Javadoc and describe what is happening and what functionality is used throughout the code. The expected input data and output data should also be described. +示例应该包括参数解析，以便你可以运行一个示例（使用 `bin/flink run path/to/myExample.jar --param1 … --param2` 从为每个示例创建的 jar 运行程序）。 Review comment: "使用 `bin/flink run path/to/myExample.jar --param1 … --param2` 从为每个示例创建的 jar 运行程序" 这个地方是不是直接写成 "使用 `bin/flink run path/to/myExample.jar --param1 … --param2` 运行程序“ 就行？现在的翻译意思是可以的，读起来有一点点拗口，简化的目的是希望读起来更顺口（当然有其他的表达方式也是可以的） ########## File path: contributing/code-style-and-quality-components.zh.md ########## @@ -48,96 +48,95 @@ How to name config keys: } ``` -* The resulting config keys should hence be: +* 因此生成的配置键应该： - **NOT** `"taskmanager.detailed.network.metrics"` + **不是** `"taskmanager.detailed.network.metrics"` - **But rather** `"taskmanager.network.detailed-metrics"` + **而是** `"taskmanager.network.detailed-metrics"` -### Connectors +### 连接器 -Connectors are historically hard to implement and need to deal with many aspects of threading, concurrency, and checkpointing. +连接器历来很难实现，需要处理多线程、并发和检查点的许多方面。 -As part of [FLIP-27](https://cwiki.apache.org/confluence/display/FLINK/FLIP-27%3A+Refactor+Source+Interface) we are working on making this much simpler for sources. New sources should not have to deal with any aspect of concurrency/threading and checkpointing any more. +作为 [FLIP-27](https://cwiki.apache.org/confluence/display/FLINK/FLIP-27%3A+Refactor+Source+Interface) 的一部分，我们正在努力让这些源（source）更加简单。新的源应该不必处理并发/线程和检查点的任何方面。 -A similar FLIP can be expected for sinks in the near future. +预计在不久的将来，会有类似针对 sink 的 FLIP。 -### Examples +### 示例 -Examples should be self-contained and not require systems other than Flink to run. Except for examples that show how to use specific connectors, like the Kafka connector. Sources/sinks that are ok to use are `StreamExecutionEnvironment.socketTextStream`, which should not be used in production but is quite handy for exploring how things work, and file-based sources/sinks. (For streaming, there is the continuous file source) +示例应该是自包含的，不需要运行 Flink 以外的系统。除了显示如何使用具体的连接器的示例，比如 Kafka 连接器。源/接收器可以使用 `StreamExecutionEnvironment.socketTextStream`，这个不应该在生产中使用，但对于研究示例如何运行是相当方便的，以及基于文件的源/接收器。（对于流，有连续的文件源） Review comment: 整个文档中的 "source" "sink" 这些次建议统一 1. “source” 在整个文档中进行统一，要么都不翻译，翻译的话都翻译成同样的词语 2. "source" 和 "sink" 是一对词，建议要么都翻译，要么都不翻译 上面 64 行的 sink 是没有翻译的，这里翻译成了接收器。 ########## File path: contributing/code-style-and-quality-components.zh.md ########## @@ -48,96 +48,95 @@ How to name config keys: } ``` -* The resulting config keys should hence be: +* 因此生成的配置键应该： - **NOT** `"taskmanager.detailed.network.metrics"` + **不是** `"taskmanager.detailed.network.metrics"` - **But rather** `"taskmanager.network.detailed-metrics"` + **而是** `"taskmanager.network.detailed-metrics"` -### Connectors +### 连接器 -Connectors are historically hard to implement and need to deal with many aspects of threading, concurrency, and checkpointing. +连接器历来很难实现，需要处理多线程、并发和检查点的许多方面。 -As part of [FLIP-27](https://cwiki.apache.org/confluence/display/FLINK/FLIP-27%3A+Refactor+Source+Interface) we are working on making this much simpler for sources. New sources should not have to deal with any aspect of concurrency/threading and checkpointing any more. +作为 [FLIP-27](https://cwiki.apache.org/confluence/display/FLINK/FLIP-27%3A+Refactor+Source+Interface) 的一部分，我们正在努力让这些源（source）更加简单。新的源应该不必处理并发/线程和检查点的任何方面。 -A similar FLIP can be expected for sinks in the near future. +预计在不久的将来，会有类似针对 sink 的 FLIP。 -### Examples +### 示例 -Examples should be self-contained and not require systems other than Flink to run. Except for examples that show how to use specific connectors, like the Kafka connector. Sources/sinks that are ok to use are `StreamExecutionEnvironment.socketTextStream`, which should not be used in production but is quite handy for exploring how things work, and file-based sources/sinks. (For streaming, there is the continuous file source) +示例应该是自包含的，不需要运行 Flink 以外的系统。除了显示如何使用具体的连接器的示例，比如 Kafka 连接器。源/接收器可以使用 `StreamExecutionEnvironment.socketTextStream`，这个不应该在生产中使用，但对于研究示例如何运行是相当方便的，以及基于文件的源/接收器。（对于流，有连续的文件源） +示例也不应该是纯粹的玩具示例，而是在现实世界的代码和纯粹的抽象示例之间取得平衡。WordCount 示例到现在已经很久了，但它是一个很好的功能突出并可以做有用事情的简单代码示例。 -Examples should also not be pure toy-examples but strike a balance between real-world code and purely abstract examples. The WordCount example is quite long in the tooth by now but it’s a good showcase of simple code that highlights functionality and can do useful things. +示例中应该有不少的注释。他们可以在类级 Javadoc 中描述示例的总体思路，并且描述正在发生什么和整个代码里使用了什么功能。还应描述预期的输入数据和输出数据。 -Examples should also be heavy in comments. They should describe the general idea of the example in the class-level Javadoc and describe what is happening and what functionality is used throughout the code. The expected input data and output data should also be described. +示例应该包括参数解析，以便你可以运行一个示例（使用 `bin/flink run path/to/myExample.jar --param1 … --param2` 从为每个示例创建的 jar 运行程序）。 -Examples should include parameter parsing, so that you can run an example (from the Jar that is created for each example using `bin/flink run path/to/myExample.jar --param1 … --param2`. +### 表和 SQL API -### Table & SQL API +#### 语义 -#### Semantics +**SQL 标准应该是事实的主要来源。** -**The SQL standard should be the main source of truth.** +* 语法、语义和功能应该和 SQL 保持一致！ +* 我们不需要重造轮子。大部分问题都已经在业界广泛讨论过并写在 SQL 标准中了。 +* 我们依靠最新的标准（在写这篇文档时使用 SQL:2016 or ISO/IEC 9075:2016 [[下载]](https://standards.iso.org/ittf/PubliclyAvailableStandards/c065143_ISO_IEC_TR_19075-5_2016.zip)）。并非每个部分都可在线获取，但快速网络搜索可能对此有所帮助。 -* Syntax, semantics, and features should be aligned with SQL! -* We don’t need to reinvent the wheel. Most problems have already been discussed industry-wide and written down in the SQL standard. -* We rely on the newest standard (SQL:2016 or ISO/IEC 9075:2016 when writing this document [[download]](https://standards.iso.org/ittf/PubliclyAvailableStandards/c065143_ISO_IEC_TR_19075-5_2016.zip) ). Not every part is available online but a quick web search might help here. +讨论与标准或厂商特定解释的差异。 -Discuss divergence from the standard or vendor-specific interpretations. +* 一旦定义了语法或行为就不能轻易撤销。 +* 需要扩展或解释标准的贡献需要与社区进行深入的讨论。 +* 请通过一些对 Postgres、Microsoft SQL Server、Oracle、Hive、Calcite、Beam 等其他厂商如何处理此类案例进行初步的探讨来帮助提交者。 -* Once a syntax or behavior is defined it cannot be undone easily. -* Contributions that need to extent or interpret the standard need a thorough discussion with the community. -* Please help committers by performing some initial research about how other vendors such as Postgres, Microsoft SQL Server, Oracle, Hive, Calcite, Beam are handling such cases. +将 Table API 视为 SQL 和 Java/Scala 编程世界之间的桥梁。 -Consider the Table API as a bridge between the SQL and Java/Scala programming world. +* Table API 是一种嵌入式域特定语言，用于遵循关系模型的分析程序。 +在语法和名称方面不需要严格遵循 SQL 标准，但如果这有助于使其感觉更直观，那么可以更接近编程语言的方式/命名函数和功能。 +* Table API 可能有一些非 SQL 功能（例如 map()、flatMap() 等），但应该还是“感觉像 SQL ”。如果可能，函数和算子应该有相等的语义和命名。 -* The Table API is an Embedded Domain Specific Language for analytical programs following the relational model. -It is not required to strictly follow the SQL standard in regards of syntax and names, but can be closer to the way a programming language would do/name functions and features, if that helps make it feel more intuitive. -* The Table API might have some non-SQL features (e.g. map(), flatMap(), etc.) but should nevertheless “feel like SQL”. Functions and operations should have equal semantics and naming if possible. +#### 常见错误 -#### Common mistakes +* 添加功能时支持 SQL 的类型系统。 + * SQL 函数、连接器或格式化从一开始就应该原生的支持大多数 SQL 类型。 + * 不支持的类型会导致混淆，限制可用性，并通过多次接触相同代码路径产生开销。 + * 例如，当添加 `SHIFT_LEFT` 函数时，确保贡献足够通用，不仅适用于 `INT` 也适用于 `BIGINT` 或 `TINYINT`。 -* Support SQL’s type system when adding a feature. - * A SQL function, connector, or format should natively support most SQL types from the very beginning. - * Unsupported types lead to confusion, limit the usability, and create overhead by touching the same code paths multiple times. - * For example, when adding a `SHIFT_LEFT` function, make sure that the contribution is general enough not only for `INT` but also `BIGINT` or `TINYINT`. +#### 测试 -#### Testing +测试为空性 -Test for nullability. +* 几乎每个操作，SQL 都原生支持 `NULL`，并具有 3 值布尔逻辑。 +* 也确保测试每个功能的可空性. -* SQL natively supports `NULL` for almost every operation and has a 3-valued boolean logic. -* Make sure to test every feature for nullability as well. +尽量避免集成测试 -Avoid full integration tests +* 生成 Flink 迷你集群并为 SQL 查询执行生成代码的编译是昂贵的。 +* 避免对计划测试或 API 调用的变更进行集成测试。 +* 相反，使用单元测试验证计划器的优化计划。或者直接测试运行时的算子行为。 -* Spawning a Flink mini-cluster and performing compilation of generated code for a SQL query is expensive. -* Avoid integration tests for planner tests or variations of API calls. -* Instead, use unit tests that validate the optimized plan which comes out of a planner. Or test the behavior of a runtime operator directly. +#### 兼容性 -#### Compatibility +不要在次要版本中引入物理计划更改！ -Don’t introduce physical plan changes in minor releases! +* 流式 SQL 中状态的向后兼容性依赖于物理执行计划保持稳定的事实。否则，生成的操作名称/IDs 将发生变化，并且无法匹配和恢复状态。 +* 每个 bug 修复都会导致流式传输管道的优化物理规划发生变化，从而破坏兼容性。 Review comment: 这里应该不是说每个 bug 修复都会破坏兼容性，而是说，那些导致 "optimized physical plan" 改变的 bug fix 会破坏兼容性。 ########## File path: contributing/code-style-and-quality-components.zh.md ########## @@ -48,96 +48,95 @@ How to name config keys: } ``` -* The resulting config keys should hence be: +* 因此生成的配置键应该： - **NOT** `"taskmanager.detailed.network.metrics"` + **不是** `"taskmanager.detailed.network.metrics"` - **But rather** `"taskmanager.network.detailed-metrics"` + **而是** `"taskmanager.network.detailed-metrics"` -### Connectors +### 连接器 -Connectors are historically hard to implement and need to deal with many aspects of threading, concurrency, and checkpointing. +连接器历来很难实现，需要处理多线程、并发和检查点的许多方面。 -As part of [FLIP-27](https://cwiki.apache.org/confluence/display/FLINK/FLIP-27%3A+Refactor+Source+Interface) we are working on making this much simpler for sources. New sources should not have to deal with any aspect of concurrency/threading and checkpointing any more. +作为 [FLIP-27](https://cwiki.apache.org/confluence/display/FLINK/FLIP-27%3A+Refactor+Source+Interface) 的一部分，我们正在努力让这些源（source）更加简单。新的源应该不必处理并发/线程和检查点的任何方面。 -A similar FLIP can be expected for sinks in the near future. +预计在不久的将来，会有类似针对 sink 的 FLIP。 -### Examples +### 示例 -Examples should be self-contained and not require systems other than Flink to run. Except for examples that show how to use specific connectors, like the Kafka connector. Sources/sinks that are ok to use are `StreamExecutionEnvironment.socketTextStream`, which should not be used in production but is quite handy for exploring how things work, and file-based sources/sinks. (For streaming, there is the continuous file source) +示例应该是自包含的，不需要运行 Flink 以外的系统。除了显示如何使用具体的连接器的示例，比如 Kafka 连接器。源/接收器可以使用 `StreamExecutionEnvironment.socketTextStream`，这个不应该在生产中使用，但对于研究示例如何运行是相当方便的，以及基于文件的源/接收器。（对于流，有连续的文件源） +示例也不应该是纯粹的玩具示例，而是在现实世界的代码和纯粹的抽象示例之间取得平衡。WordCount 示例到现在已经很久了，但它是一个很好的功能突出并可以做有用事情的简单代码示例。 -Examples should also not be pure toy-examples but strike a balance between real-world code and purely abstract examples. The WordCount example is quite long in the tooth by now but it’s a good showcase of simple code that highlights functionality and can do useful things. +示例中应该有不少的注释。他们可以在类级 Javadoc 中描述示例的总体思路，并且描述正在发生什么和整个代码里使用了什么功能。还应描述预期的输入数据和输出数据。 -Examples should also be heavy in comments. They should describe the general idea of the example in the class-level Javadoc and describe what is happening and what functionality is used throughout the code. The expected input data and output data should also be described. +示例应该包括参数解析，以便你可以运行一个示例（使用 `bin/flink run path/to/myExample.jar --param1 … --param2` 从为每个示例创建的 jar 运行程序）。 -Examples should include parameter parsing, so that you can run an example (from the Jar that is created for each example using `bin/flink run path/to/myExample.jar --param1 … --param2`. +### 表和 SQL API -### Table & SQL API +#### 语义 -#### Semantics +**SQL 标准应该是事实的主要来源。** -**The SQL standard should be the main source of truth.** +* 语法、语义和功能应该和 SQL 保持一致！ +* 我们不需要重造轮子。大部分问题都已经在业界广泛讨论过并写在 SQL 标准中了。 +* 我们依靠最新的标准（在写这篇文档时使用 SQL:2016 or ISO/IEC 9075:2016 [[下载]](https://standards.iso.org/ittf/PubliclyAvailableStandards/c065143_ISO_IEC_TR_19075-5_2016.zip)）。并非每个部分都可在线获取，但快速网络搜索可能对此有所帮助。 -* Syntax, semantics, and features should be aligned with SQL! -* We don’t need to reinvent the wheel. Most problems have already been discussed industry-wide and written down in the SQL standard. -* We rely on the newest standard (SQL:2016 or ISO/IEC 9075:2016 when writing this document [[download]](https://standards.iso.org/ittf/PubliclyAvailableStandards/c065143_ISO_IEC_TR_19075-5_2016.zip) ). Not every part is available online but a quick web search might help here. +讨论与标准或厂商特定解释的差异。 -Discuss divergence from the standard or vendor-specific interpretations. +* 一旦定义了语法或行为就不能轻易撤销。 +* 需要扩展或解释标准的贡献需要与社区进行深入的讨论。 +* 请通过一些对 Postgres、Microsoft SQL Server、Oracle、Hive、Calcite、Beam 等其他厂商如何处理此类案例进行初步的探讨来帮助提交者。 -* Once a syntax or behavior is defined it cannot be undone easily. -* Contributions that need to extent or interpret the standard need a thorough discussion with the community. -* Please help committers by performing some initial research about how other vendors such as Postgres, Microsoft SQL Server, Oracle, Hive, Calcite, Beam are handling such cases. +将 Table API 视为 SQL 和 Java/Scala 编程世界之间的桥梁。 -Consider the Table API as a bridge between the SQL and Java/Scala programming world. +* Table API 是一种嵌入式域特定语言，用于遵循关系模型的分析程序。 +在语法和名称方面不需要严格遵循 SQL 标准，但如果这有助于使其感觉更直观，那么可以更接近编程语言的方式/命名函数和功能。 +* Table API 可能有一些非 SQL 功能（例如 map()、flatMap() 等），但应该还是“感觉像 SQL ”。如果可能，函数和算子应该有相等的语义和命名。 Review comment: ```suggestion * Table API 可能有一些非 SQL 功能（例如 map()、flatMap() 等），但应该还是“感觉像 SQL”。如果可能，函数和算子应该有相等的语义和命名。 ``` 另外 `但应该还是“感觉像 SQL”` 这句话需要改成 `但还是应该“感觉像 SQL”` 会好一些吗？ ########## File path: contributing/code-style-and-quality-components.zh.md ########## @@ -48,96 +48,95 @@ How to name config keys: } ``` -* The resulting config keys should hence be: +* 因此生成的配置键应该： - **NOT** `"taskmanager.detailed.network.metrics"` + **不是** `"taskmanager.detailed.network.metrics"` - **But rather** `"taskmanager.network.detailed-metrics"` + **而是** `"taskmanager.network.detailed-metrics"` -### Connectors +### 连接器 -Connectors are historically hard to implement and need to deal with many aspects of threading, concurrency, and checkpointing. +连接器历来很难实现，需要处理多线程、并发和检查点的许多方面。 -As part of [FLIP-27](https://cwiki.apache.org/confluence/display/FLINK/FLIP-27%3A+Refactor+Source+Interface) we are working on making this much simpler for sources. New sources should not have to deal with any aspect of concurrency/threading and checkpointing any more. +作为 [FLIP-27](https://cwiki.apache.org/confluence/display/FLINK/FLIP-27%3A+Refactor+Source+Interface) 的一部分，我们正在努力让这些源（source）更加简单。新的源应该不必处理并发/线程和检查点的任何方面。 -A similar FLIP can be expected for sinks in the near future. +预计在不久的将来，会有类似针对 sink 的 FLIP。 -### Examples +### 示例 -Examples should be self-contained and not require systems other than Flink to run. Except for examples that show how to use specific connectors, like the Kafka connector. Sources/sinks that are ok to use are `StreamExecutionEnvironment.socketTextStream`, which should not be used in production but is quite handy for exploring how things work, and file-based sources/sinks. (For streaming, there is the continuous file source) +示例应该是自包含的，不需要运行 Flink 以外的系统。除了显示如何使用具体的连接器的示例，比如 Kafka 连接器。源/接收器可以使用 `StreamExecutionEnvironment.socketTextStream`，这个不应该在生产中使用，但对于研究示例如何运行是相当方便的，以及基于文件的源/接收器。（对于流，有连续的文件源） +示例也不应该是纯粹的玩具示例，而是在现实世界的代码和纯粹的抽象示例之间取得平衡。WordCount 示例到现在已经很久了，但它是一个很好的功能突出并可以做有用事情的简单代码示例。 -Examples should also not be pure toy-examples but strike a balance between real-world code and purely abstract examples. The WordCount example is quite long in the tooth by now but it’s a good showcase of simple code that highlights functionality and can do useful things. +示例中应该有不少的注释。他们可以在类级 Javadoc 中描述示例的总体思路，并且描述正在发生什么和整个代码里使用了什么功能。还应描述预期的输入数据和输出数据。 -Examples should also be heavy in comments. They should describe the general idea of the example in the class-level Javadoc and describe what is happening and what functionality is used throughout the code. The expected input data and output data should also be described. +示例应该包括参数解析，以便你可以运行一个示例（使用 `bin/flink run path/to/myExample.jar --param1 … --param2` 从为每个示例创建的 jar 运行程序）。 -Examples should include parameter parsing, so that you can run an example (from the Jar that is created for each example using `bin/flink run path/to/myExample.jar --param1 … --param2`. +### 表和 SQL API -### Table & SQL API +#### 语义 -#### Semantics +**SQL 标准应该是事实的主要来源。** -**The SQL standard should be the main source of truth.** +* 语法、语义和功能应该和 SQL 保持一致！ +* 我们不需要重造轮子。大部分问题都已经在业界广泛讨论过并写在 SQL 标准中了。 +* 我们依靠最新的标准（在写这篇文档时使用 SQL:2016 or ISO/IEC 9075:2016 [[下载]](https://standards.iso.org/ittf/PubliclyAvailableStandards/c065143_ISO_IEC_TR_19075-5_2016.zip)）。并非每个部分都可在线获取，但快速网络搜索可能对此有所帮助。 -* Syntax, semantics, and features should be aligned with SQL! -* We don’t need to reinvent the wheel. Most problems have already been discussed industry-wide and written down in the SQL standard. -* We rely on the newest standard (SQL:2016 or ISO/IEC 9075:2016 when writing this document [[download]](https://standards.iso.org/ittf/PubliclyAvailableStandards/c065143_ISO_IEC_TR_19075-5_2016.zip) ). Not every part is available online but a quick web search might help here. +讨论与标准或厂商特定解释的差异。 -Discuss divergence from the standard or vendor-specific interpretations. +* 一旦定义了语法或行为就不能轻易撤销。 +* 需要扩展或解释标准的贡献需要与社区进行深入的讨论。 +* 请通过一些对 Postgres、Microsoft SQL Server、Oracle、Hive、Calcite、Beam 等其他厂商如何处理此类案例进行初步的探讨来帮助提交者。 -* Once a syntax or behavior is defined it cannot be undone easily. -* Contributions that need to extent or interpret the standard need a thorough discussion with the community. -* Please help committers by performing some initial research about how other vendors such as Postgres, Microsoft SQL Server, Oracle, Hive, Calcite, Beam are handling such cases. +将 Table API 视为 SQL 和 Java/Scala 编程世界之间的桥梁。 -Consider the Table API as a bridge between the SQL and Java/Scala programming world. +* Table API 是一种嵌入式域特定语言，用于遵循关系模型的分析程序。 +在语法和名称方面不需要严格遵循 SQL 标准，但如果这有助于使其感觉更直观，那么可以更接近编程语言的方式/命名函数和功能。 +* Table API 可能有一些非 SQL 功能（例如 map()、flatMap() 等），但应该还是“感觉像 SQL ”。如果可能，函数和算子应该有相等的语义和命名。 -* The Table API is an Embedded Domain Specific Language for analytical programs following the relational model. -It is not required to strictly follow the SQL standard in regards of syntax and names, but can be closer to the way a programming language would do/name functions and features, if that helps make it feel more intuitive. -* The Table API might have some non-SQL features (e.g. map(), flatMap(), etc.) but should nevertheless “feel like SQL”. Functions and operations should have equal semantics and naming if possible. +#### 常见错误 -#### Common mistakes +* 添加功能时支持 SQL 的类型系统。 + * SQL 函数、连接器或格式化从一开始就应该原生的支持大多数 SQL 类型。 + * 不支持的类型会导致混淆，限制可用性，并通过多次接触相同代码路径产生开销。 + * 例如，当添加 `SHIFT_LEFT` 函数时，确保贡献足够通用，不仅适用于 `INT` 也适用于 `BIGINT` 或 `TINYINT`。 -* Support SQL’s type system when adding a feature. - * A SQL function, connector, or format should natively support most SQL types from the very beginning. - * Unsupported types lead to confusion, limit the usability, and create overhead by touching the same code paths multiple times. - * For example, when adding a `SHIFT_LEFT` function, make sure that the contribution is general enough not only for `INT` but also `BIGINT` or `TINYINT`. +#### 测试 -#### Testing +测试为空性 -Test for nullability. +* 几乎每个操作，SQL 都原生支持 `NULL`，并具有 3 值布尔逻辑。 +* 也确保测试每个功能的可空性. -* SQL natively supports `NULL` for almost every operation and has a 3-valued boolean logic. -* Make sure to test every feature for nullability as well. +尽量避免集成测试 -Avoid full integration tests +* 生成 Flink 迷你集群并为 SQL 查询执行生成代码的编译是昂贵的。 +* 避免对计划测试或 API 调用的变更进行集成测试。 +* 相反，使用单元测试验证计划器的优化计划。或者直接测试运行时的算子行为。 -* Spawning a Flink mini-cluster and performing compilation of generated code for a SQL query is expensive. -* Avoid integration tests for planner tests or variations of API calls. -* Instead, use unit tests that validate the optimized plan which comes out of a planner. Or test the behavior of a runtime operator directly. +#### 兼容性 -#### Compatibility +不要在次要版本中引入物理计划更改！ -Don’t introduce physical plan changes in minor releases! +* 流式 SQL 中状态的向后兼容性依赖于物理执行计划保持稳定的事实。否则，生成的操作名称/IDs 将发生变化，并且无法匹配和恢复状态。 +* 每个 bug 修复都会导致流式传输管道的优化物理规划发生变化，从而破坏兼容性。 +* 因此，导致不同优化器计划的更改现在只能在主版本中合并。 Review comment: 这里有比 ”主板本“ 更好的翻译吗？这里想表达的意思，这些只能在 "1.8.0", "1.9.0", "1.10.0" 这些大版本 merge，不能在 "1.9.1", "1.10.1" 这些小班本 merge 主板本相对就是”次版本“或者”副版本“，”次版本“/”副版本“ 有一种不重要的感觉 ########## File path: contributing/code-style-and-quality-components.zh.md ########## @@ -48,96 +48,95 @@ How to name config keys: } ``` -* The resulting config keys should hence be: +* 因此生成的配置键应该： - **NOT** `"taskmanager.detailed.network.metrics"` + **不是** `"taskmanager.detailed.network.metrics"` - **But rather** `"taskmanager.network.detailed-metrics"` + **而是** `"taskmanager.network.detailed-metrics"` -### Connectors +### 连接器 -Connectors are historically hard to implement and need to deal with many aspects of threading, concurrency, and checkpointing. +连接器历来很难实现，需要处理多线程、并发和检查点的许多方面。 -As part of [FLIP-27](https://cwiki.apache.org/confluence/display/FLINK/FLIP-27%3A+Refactor+Source+Interface) we are working on making this much simpler for sources. New sources should not have to deal with any aspect of concurrency/threading and checkpointing any more. +作为 [FLIP-27](https://cwiki.apache.org/confluence/display/FLINK/FLIP-27%3A+Refactor+Source+Interface) 的一部分，我们正在努力让这些源（source）更加简单。新的源应该不必处理并发/线程和检查点的任何方面。 -A similar FLIP can be expected for sinks in the near future. +预计在不久的将来，会有类似针对 sink 的 FLIP。 -### Examples +### 示例 -Examples should be self-contained and not require systems other than Flink to run. Except for examples that show how to use specific connectors, like the Kafka connector. Sources/sinks that are ok to use are `StreamExecutionEnvironment.socketTextStream`, which should not be used in production but is quite handy for exploring how things work, and file-based sources/sinks. (For streaming, there is the continuous file source) +示例应该是自包含的，不需要运行 Flink 以外的系统。除了显示如何使用具体的连接器的示例，比如 Kafka 连接器。源/接收器可以使用 `StreamExecutionEnvironment.socketTextStream`，这个不应该在生产中使用，但对于研究示例如何运行是相当方便的，以及基于文件的源/接收器。（对于流，有连续的文件源） +示例也不应该是纯粹的玩具示例，而是在现实世界的代码和纯粹的抽象示例之间取得平衡。WordCount 示例到现在已经很久了，但它是一个很好的功能突出并可以做有用事情的简单代码示例。 -Examples should also not be pure toy-examples but strike a balance between real-world code and purely abstract examples. The WordCount example is quite long in the tooth by now but it’s a good showcase of simple code that highlights functionality and can do useful things. +示例中应该有不少的注释。他们可以在类级 Javadoc 中描述示例的总体思路，并且描述正在发生什么和整个代码里使用了什么功能。还应描述预期的输入数据和输出数据。 -Examples should also be heavy in comments. They should describe the general idea of the example in the class-level Javadoc and describe what is happening and what functionality is used throughout the code. The expected input data and output data should also be described. +示例应该包括参数解析，以便你可以运行一个示例（使用 `bin/flink run path/to/myExample.jar --param1 … --param2` 从为每个示例创建的 jar 运行程序）。 -Examples should include parameter parsing, so that you can run an example (from the Jar that is created for each example using `bin/flink run path/to/myExample.jar --param1 … --param2`. +### 表和 SQL API -### Table & SQL API +#### 语义 -#### Semantics +**SQL 标准应该是事实的主要来源。** -**The SQL standard should be the main source of truth.** +* 语法、语义和功能应该和 SQL 保持一致！ +* 我们不需要重造轮子。大部分问题都已经在业界广泛讨论过并写在 SQL 标准中了。 +* 我们依靠最新的标准（在写这篇文档时使用 SQL:2016 or ISO/IEC 9075:2016 [[下载]](https://standards.iso.org/ittf/PubliclyAvailableStandards/c065143_ISO_IEC_TR_19075-5_2016.zip)）。并非每个部分都可在线获取，但快速网络搜索可能对此有所帮助。 -* Syntax, semantics, and features should be aligned with SQL! -* We don’t need to reinvent the wheel. Most problems have already been discussed industry-wide and written down in the SQL standard. -* We rely on the newest standard (SQL:2016 or ISO/IEC 9075:2016 when writing this document [[download]](https://standards.iso.org/ittf/PubliclyAvailableStandards/c065143_ISO_IEC_TR_19075-5_2016.zip) ). Not every part is available online but a quick web search might help here. +讨论与标准或厂商特定解释的差异。 -Discuss divergence from the standard or vendor-specific interpretations. +* 一旦定义了语法或行为就不能轻易撤销。 +* 需要扩展或解释标准的贡献需要与社区进行深入的讨论。 +* 请通过一些对 Postgres、Microsoft SQL Server、Oracle、Hive、Calcite、Beam 等其他厂商如何处理此类案例进行初步的探讨来帮助提交者。 -* Once a syntax or behavior is defined it cannot be undone easily. -* Contributions that need to extent or interpret the standard need a thorough discussion with the community. -* Please help committers by performing some initial research about how other vendors such as Postgres, Microsoft SQL Server, Oracle, Hive, Calcite, Beam are handling such cases. +将 Table API 视为 SQL 和 Java/Scala 编程世界之间的桥梁。 -Consider the Table API as a bridge between the SQL and Java/Scala programming world. +* Table API 是一种嵌入式域特定语言，用于遵循关系模型的分析程序。 +在语法和名称方面不需要严格遵循 SQL 标准，但如果这有助于使其感觉更直观，那么可以更接近编程语言的方式/命名函数和功能。 +* Table API 可能有一些非 SQL 功能（例如 map()、flatMap() 等），但应该还是“感觉像 SQL ”。如果可能，函数和算子应该有相等的语义和命名。 -* The Table API is an Embedded Domain Specific Language for analytical programs following the relational model. -It is not required to strictly follow the SQL standard in regards of syntax and names, but can be closer to the way a programming language would do/name functions and features, if that helps make it feel more intuitive. -* The Table API might have some non-SQL features (e.g. map(), flatMap(), etc.) but should nevertheless “feel like SQL”. Functions and operations should have equal semantics and naming if possible. +#### 常见错误 -#### Common mistakes +* 添加功能时支持 SQL 的类型系统。 + * SQL 函数、连接器或格式化从一开始就应该原生的支持大多数 SQL 类型。 + * 不支持的类型会导致混淆，限制可用性，并通过多次接触相同代码路径产生开销。 + * 例如，当添加 `SHIFT_LEFT` 函数时，确保贡献足够通用，不仅适用于 `INT` 也适用于 `BIGINT` 或 `TINYINT`。 -* Support SQL’s type system when adding a feature. - * A SQL function, connector, or format should natively support most SQL types from the very beginning. - * Unsupported types lead to confusion, limit the usability, and create overhead by touching the same code paths multiple times. - * For example, when adding a `SHIFT_LEFT` function, make sure that the contribution is general enough not only for `INT` but also `BIGINT` or `TINYINT`. +#### 测试 -#### Testing +测试为空性 -Test for nullability. +* 几乎每个操作，SQL 都原生支持 `NULL`，并具有 3 值布尔逻辑。 +* 也确保测试每个功能的可空性. -* SQL natively supports `NULL` for almost every operation and has a 3-valued boolean logic. -* Make sure to test every feature for nullability as well. +尽量避免集成测试 -Avoid full integration tests +* 生成 Flink 迷你集群并为 SQL 查询执行生成代码的编译是昂贵的。 +* 避免对计划测试或 API 调用的变更进行集成测试。 +* 相反，使用单元测试验证计划器的优化计划。或者直接测试运行时的算子行为。 -* Spawning a Flink mini-cluster and performing compilation of generated code for a SQL query is expensive. -* Avoid integration tests for planner tests or variations of API calls. -* Instead, use unit tests that validate the optimized plan which comes out of a planner. Or test the behavior of a runtime operator directly. +#### 兼容性 -#### Compatibility +不要在次要版本中引入物理计划更改！ -Don’t introduce physical plan changes in minor releases! +* 流式 SQL 中状态的向后兼容性依赖于物理执行计划保持稳定的事实。否则，生成的操作名称/IDs 将发生变化，并且无法匹配和恢复状态。 +* 每个 bug 修复都会导致流式传输管道的优化物理规划发生变化，从而破坏兼容性。 +* 因此，导致不同优化器计划的更改现在只能在主版本中合并。 -* Backwards compatibility for state in streaming SQL relies on the fact that the physical execution plan remains stable. Otherwise the generated Operator Names/IDs change and state cannot be matched and restored. -* Every bug fix that leads to changes in the optimized physical plan of a streaming pipeline hences breaks compatibility. -* As a consequence, changes of the kind that lead to different optimizer plans can only be merged in major releases for now. +#### Scala / Java 互操作性（遗留代码部分） -#### Scala / Java interoperability (legacy code parts) +在设计接口时要牢记 Java。 -Keep Java in mind when designing interfaces. - -* Consider whether a class will need to interact with a Java class in the future. -* Use Java collections and Java Optional in interfaces for a smooth integration with Java code. -* Don’t use features of case classes such as .copy() or apply() for construction if a class is subjected to be converted to Java. -* Pure Scala user-facing APIs should use pure Scala collections/iterables/etc. for natural and idiomatic (“scalaesk”) integration with Scala. +* 考虑一个类将来是否需要与 Java 类交互。 +* 在接口中使用 Java 集合和 Java Optional，以便与 Java 代码平滑集成。 +* 如果要将类转换为 Java，不要使用 .copy() 或 apply() 等案例类的功能进行构造。 Review comment: ”case class“ 翻译成 ”案例类“ 个人没见过这个中文表述方式，可以考虑是否还有其他更好的翻译/不需要翻译。或者看其他人的意见。 ########## File path: contributing/code-style-and-quality-components.zh.md ########## @@ -48,96 +48,95 @@ How to name config keys: } ``` -* The resulting config keys should hence be: +* 因此生成的配置键应该： - **NOT** `"taskmanager.detailed.network.metrics"` + **不是** `"taskmanager.detailed.network.metrics"` - **But rather** `"taskmanager.network.detailed-metrics"` + **而是** `"taskmanager.network.detailed-metrics"` -### Connectors +### 连接器 -Connectors are historically hard to implement and need to deal with many aspects of threading, concurrency, and checkpointing. +连接器历来很难实现，需要处理多线程、并发和检查点的许多方面。 -As part of [FLIP-27](https://cwiki.apache.org/confluence/display/FLINK/FLIP-27%3A+Refactor+Source+Interface) we are working on making this much simpler for sources. New sources should not have to deal with any aspect of concurrency/threading and checkpointing any more. +作为 [FLIP-27](https://cwiki.apache.org/confluence/display/FLINK/FLIP-27%3A+Refactor+Source+Interface) 的一部分，我们正在努力让这些源（source）更加简单。新的源应该不必处理并发/线程和检查点的任何方面。 -A similar FLIP can be expected for sinks in the near future. +预计在不久的将来，会有类似针对 sink 的 FLIP。 -### Examples +### 示例 -Examples should be self-contained and not require systems other than Flink to run. Except for examples that show how to use specific connectors, like the Kafka connector. Sources/sinks that are ok to use are `StreamExecutionEnvironment.socketTextStream`, which should not be used in production but is quite handy for exploring how things work, and file-based sources/sinks. (For streaming, there is the continuous file source) +示例应该是自包含的，不需要运行 Flink 以外的系统。除了显示如何使用具体的连接器的示例，比如 Kafka 连接器。源/接收器可以使用 `StreamExecutionEnvironment.socketTextStream`，这个不应该在生产中使用，但对于研究示例如何运行是相当方便的，以及基于文件的源/接收器。（对于流，有连续的文件源） +示例也不应该是纯粹的玩具示例，而是在现实世界的代码和纯粹的抽象示例之间取得平衡。WordCount 示例到现在已经很久了，但它是一个很好的功能突出并可以做有用事情的简单代码示例。 -Examples should also not be pure toy-examples but strike a balance between real-world code and purely abstract examples. The WordCount example is quite long in the tooth by now but it’s a good showcase of simple code that highlights functionality and can do useful things. +示例中应该有不少的注释。他们可以在类级 Javadoc 中描述示例的总体思路，并且描述正在发生什么和整个代码里使用了什么功能。还应描述预期的输入数据和输出数据。 -Examples should also be heavy in comments. They should describe the general idea of the example in the class-level Javadoc and describe what is happening and what functionality is used throughout the code. The expected input data and output data should also be described. +示例应该包括参数解析，以便你可以运行一个示例（使用 `bin/flink run path/to/myExample.jar --param1 … --param2` 从为每个示例创建的 jar 运行程序）。 -Examples should include parameter parsing, so that you can run an example (from the Jar that is created for each example using `bin/flink run path/to/myExample.jar --param1 … --param2`. +### 表和 SQL API -### Table & SQL API +#### 语义 -#### Semantics +**SQL 标准应该是事实的主要来源。** -**The SQL standard should be the main source of truth.** +* 语法、语义和功能应该和 SQL 保持一致！ +* 我们不需要重造轮子。大部分问题都已经在业界广泛讨论过并写在 SQL 标准中了。 +* 我们依靠最新的标准（在写这篇文档时使用 SQL:2016 or ISO/IEC 9075:2016 [[下载]](https://standards.iso.org/ittf/PubliclyAvailableStandards/c065143_ISO_IEC_TR_19075-5_2016.zip)）。并非每个部分都可在线获取，但快速网络搜索可能对此有所帮助。 -* Syntax, semantics, and features should be aligned with SQL! -* We don’t need to reinvent the wheel. Most problems have already been discussed industry-wide and written down in the SQL standard. -* We rely on the newest standard (SQL:2016 or ISO/IEC 9075:2016 when writing this document [[download]](https://standards.iso.org/ittf/PubliclyAvailableStandards/c065143_ISO_IEC_TR_19075-5_2016.zip) ). Not every part is available online but a quick web search might help here. +讨论与标准或厂商特定解释的差异。 -Discuss divergence from the standard or vendor-specific interpretations. +* 一旦定义了语法或行为就不能轻易撤销。 +* 需要扩展或解释标准的贡献需要与社区进行深入的讨论。 +* 请通过一些对 Postgres、Microsoft SQL Server、Oracle、Hive、Calcite、Beam 等其他厂商如何处理此类案例进行初步的探讨来帮助提交者。 -* Once a syntax or behavior is defined it cannot be undone easily. -* Contributions that need to extent or interpret the standard need a thorough discussion with the community. -* Please help committers by performing some initial research about how other vendors such as Postgres, Microsoft SQL Server, Oracle, Hive, Calcite, Beam are handling such cases. +将 Table API 视为 SQL 和 Java/Scala 编程世界之间的桥梁。 -Consider the Table API as a bridge between the SQL and Java/Scala programming world. +* Table API 是一种嵌入式域特定语言，用于遵循关系模型的分析程序。 +在语法和名称方面不需要严格遵循 SQL 标准，但如果这有助于使其感觉更直观，那么可以更接近编程语言的方式/命名函数和功能。 +* Table API 可能有一些非 SQL 功能（例如 map()、flatMap() 等），但应该还是“感觉像 SQL ”。如果可能，函数和算子应该有相等的语义和命名。 -* The Table API is an Embedded Domain Specific Language for analytical programs following the relational model. -It is not required to strictly follow the SQL standard in regards of syntax and names, but can be closer to the way a programming language would do/name functions and features, if that helps make it feel more intuitive. -* The Table API might have some non-SQL features (e.g. map(), flatMap(), etc.) but should nevertheless “feel like SQL”. Functions and operations should have equal semantics and naming if possible. +#### 常见错误 -#### Common mistakes +* 添加功能时支持 SQL 的类型系统。 + * SQL 函数、连接器或格式化从一开始就应该原生的支持大多数 SQL 类型。 + * 不支持的类型会导致混淆，限制可用性，并通过多次接触相同代码路径产生开销。 + * 例如，当添加 `SHIFT_LEFT` 函数时，确保贡献足够通用，不仅适用于 `INT` 也适用于 `BIGINT` 或 `TINYINT`。 -* Support SQL’s type system when adding a feature. - * A SQL function, connector, or format should natively support most SQL types from the very beginning. - * Unsupported types lead to confusion, limit the usability, and create overhead by touching the same code paths multiple times. - * For example, when adding a `SHIFT_LEFT` function, make sure that the contribution is general enough not only for `INT` but also `BIGINT` or `TINYINT`. +#### 测试 -#### Testing +测试为空性 -Test for nullability. +* 几乎每个操作，SQL 都原生支持 `NULL`，并具有 3 值布尔逻辑。 +* 也确保测试每个功能的可空性. -* SQL natively supports `NULL` for almost every operation and has a 3-valued boolean logic. -* Make sure to test every feature for nullability as well. +尽量避免集成测试 -Avoid full integration tests +* 生成 Flink 迷你集群并为 SQL 查询执行生成代码的编译是昂贵的。 +* 避免对计划测试或 API 调用的变更进行集成测试。 +* 相反，使用单元测试验证计划器的优化计划。或者直接测试运行时的算子行为。 -* Spawning a Flink mini-cluster and performing compilation of generated code for a SQL query is expensive. -* Avoid integration tests for planner tests or variations of API calls. -* Instead, use unit tests that validate the optimized plan which comes out of a planner. Or test the behavior of a runtime operator directly. +#### 兼容性 -#### Compatibility +不要在次要版本中引入物理计划更改！ -Don’t introduce physical plan changes in minor releases! +* 流式 SQL 中状态的向后兼容性依赖于物理执行计划保持稳定的事实。否则，生成的操作名称/IDs 将发生变化，并且无法匹配和恢复状态。 Review comment: 这里 ”operator names/IDs" 是不是翻译成 “算子名称/IDs” 会更好，或者能否不翻译呢？（有其他更好的翻译也是欢迎的） 因为翻译成 “算子名称/IDs" 可能给别人理解的是 ”算子名称“和 ”IDs“两个东西，但实际我们想表达的是 ”算子名称“和 ”算子 IDs“ ---------------------------------------------------------------- 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. For queries about this service, please contact Infrastructure at: [email protected]
