\newcommand{\R}{\mathbb{R}} \newcommand{\E}{\mathbb{E}} \newcommand{\x}{\mathbf{x}} \newcommand{\y}{\mathbf{y}} \newcommand{\wv}{\mathbf{w}} \newcommand{\av}{\mathbf{\alpha}} \newcommand{\bv}{\mathbf{b}} \newcommand{\N}{\mathbb{N}} \newcommand{\id}{\mathbf{I}} \newcommand{\ind}{\mathbf{1}} \newcommand{\0}{\mathbf{0}} \newcommand{\unit}{\mathbf{e}} \newcommand{\one}{\mathbf{1}} \newcommand{\zero}{\mathbf{0}} \newcommand\rfrac[2]{^{#1}!/_{#2}} \newcommand{\norm}[1]{\left\lVert#1\right\rVert}

如何贡献

Flink社区高度赞赏对FlinkML的各种贡献。FlinkML为对机器学习感兴趣的人提供了一个非常活跃的开源项目，实现了可伸缩的机器学习。下面的文档描述了如何为FlinkML做贡献。

开始

首先需要阅读flink的贡献指南。这个指南的所有内容同样适用于FlinkML。

选择一个话题

如果您正在寻找一些新的想法，您应该首先查看我们的roadmap,然后查看JIRA上未解决的问题列表。一旦你决定为这些issue中的一个做出贡献，你就应该对它有主人翁意识，并跟踪你在这个issue上的进展。这样其他贡献者就知道不同issue的状态，从而避免了冗余工作。

如果您已经知道您想为FlinkML贡献什么，那就更好了。不过，仍然建议您创建一个JIRA issue，以便告诉Flink社区您想做什么。

测试

新的贡献应该与测试一起来验证算法的正确性。同时测试有助于在整个代码修改(例如重构)过程中保持算法的正确性。

我们区分了单元测试(在Maven的test阶段执行)和集成测试(在Maven的verify阶段执行)。Maven通过使用以下命名规则自动进行这种区分:所有类名以满足正则表达式“(IT|Integration)(test |Suite|Case)”后缀结尾的测试用例都被认为是集成测试。其余的被认为是单元测试，并且应该只测试被测试组件的本地行为。

集成测试是需要启动整个Flink系统的测试。为了正确地做到这一点，所有的集成测试用例都必须混合使用特性“FlinkTestBase”。此特性将设置正确的ExecutionEnvironment，以便指定在“FlinkMiniCluster”(用于测试目的)上执行测试。因此，集成测试可以如下:

  1. class ExampleITSuite extends FlatSpec with FlinkTestBase {
  2.   behavior of "An example algorithm"
  4.   it should "do something" in {
  5.     ...
  6.   }
  7. }

测试样式不必是“FlatSpec”，可以是任何其他最大规模的“Suite”子类。有关更多信息，请参见ScalaTest testing styles。

文档

在提供新的算法时，需要添加代码注释，描述算法的工作方式及其参数，这样用户可以使用这些代码注释控制算法的行为。此外，我们希望鼓励贡献者将此信息添加到在线文档中。FlinkML组件的在线文档可以在“docs/libs/ml”目录下找到。

每个新算法都由一个markdown文件描述。该文件至少应包含以下几点:

  1. 这个算法是做什么的
  2. 算法如何工作(或参考描述)
  3. 参数描述，带有默认值
  4. 展示如何使用算法的代码片段

为了在markdown文件中使用latex语法，必须在YAML前端内容中包含’mathjax: include’。

  1. ---
  2. mathjax: include
  3. htmlTitle: FlinkML - Example title
  4. title: <a href="../ml">FlinkML</a> - Example title
  5. ---

为了使用显示数学，您必须将latex代码输入在’…’中。对于内联数学，使用’$…$’。此外，一些预定义的latex命令包含在markdown文件内。详见’docs/_include/latex_commands.html’获取预定义latex命令的完整列表。

贡献中

一旦实现了具有足够的测试覆盖率和添加文档的算法，就可以pull请求了。有关如何打开pull请求的详细信息可以在这里找到。