 $$ \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的[贡献指南](http://flink.apache.org/how-to-contribute.html)。这个指南的所有内容同样适用于FlinkML。

## 选择一个话题

如果您正在寻找一些新的想法，您应该首先查看我们的[roadmap](https://cwiki.apache.org/confluence/display/FLINK/FlinkML%3A+Vision+and+Roadmap),然后查看[JIRA上未解决的问题列表](https://issues.apache.org/jira/issues/?jql=component%20%3D%20%22Machine%20Learning%20Library%22%20AND%20project%20%3D%20FLINK%20AND%20resolution%20%3D%20Unresolved%20ORDER%20BY%20priority%20DESC)。一旦你决定为这些issue中的一个做出贡献，你就应该对它有主人翁意识，并跟踪你在这个issue上的进展。这样其他贡献者就知道不同issue的状态，从而避免了冗余工作。

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

## 测试

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

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

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

```
class ExampleITSuite extends FlatSpec with FlinkTestBase {
  behavior of "An example algorithm"

  it should "do something" in {
    ...
  }
}
```

测试样式不必是“FlatSpec”，可以是任何其他最大规模的“Suite”子类。有关更多信息，请参见[ScalaTest testing styles](http://scalatest.org/user_guide/selecting_a_style)。

## 文档

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

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

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

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


```
---
mathjax: include
htmlTitle: FlinkML - Example title
title: <a href="../ml">FlinkML</a> - Example title
---
```

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

## 贡献中

一旦实现了具有足够的测试覆盖率和添加文档的算法，就可以pull请求了。有关如何打开pull请求的详细信息可以在[这里](http://flink.apache.org/how-to-contribute.html#contributing-code--documentation)找到。


