怎样贡献代码给spark team

以前总是想着贡献源码，只是想想罢了，没有认真去做过。

今天突发奇想，觉得是不是可以尝试着看看呢？虽然是菜鸟，但是菜鸟也能看看吧！

于是打开spark的官方文档，迈出了第一步，希望这篇文章能对想贡献源码给spark team的朋友有用。

由于水平有限，文章稍微粗糙,如需查看原文，请见：http://spark.apache.org/contributing.html

译文如下：

本指南记录了对Apache Spark进行各种类型贡献的最佳方法，包括在提交代码更改之前需要执行的操作。

贡献给Spark不只是意味着编写代码。 还欢迎帮助新用户查看邮件列表，测试版本和改进文档。 事实上，提出重大的代码更改通常需要首先通过hping在其他方式获得经验和社区内的信誉。 这也是成为有效贡献者的指南。

因此，本指南组织捐款，以便他们可能应由想要长期参与的新捐助者考虑。 建立一些帮助他人的记录，而不是只是打开拉请求。

一、通过帮助其他用户

一个伟大的方式来贡献Spark是帮助回答用户问题在[e-mail]邮件列表或StackOverflow。 总有很多新的Spark用户; 花几分钟时间帮助回答一个问题是一个非常有价值的社区服务。

贡献者应该订阅此列表并跟踪它，以便及时了解Spark中发生的事情。 回答问题是一个很好的和可见的方式来帮助社区，这也表明你的专业知识。

有关如何有效参与邮件列表讨论以及StackOverflow等论坛的指导，请参阅邮件列表指南。

二、通过测试发布

Spark的发布过程是面向社区的，社区成员可以在[e-mail]邮件列表上对新版本进行投票。 Spark用户被邀请订阅此列表以接收通知，并在较新版本上测试其工作负载，并提供有关新版本中发现的任何性能或正确性问题的反馈。

三、通过审阅更改做出贡献

Spark源代码的更改通过Github pull请求（稍后描述）提出，审核和提交。 任何人都可以在这里查看和评论主动更改。 回顾其他人的变化是了解变化过程如何工作并获得代码各部分活动的好方法。 您可以通过查看更改并提出问题或指出问题，如拼写错误或小问题的风格，帮助。 另请参见https://spark-prs.appspot.com/，以便查看和过滤公开的PR。

四、贡献文档更改

要提出发布文档的更改（即，显示在https://spark.apache.org/docs/下的文档），请编辑Spark的docs /目录中的Markdown源文件，其中的README文件显示如何在本地构建文档 以测试您的更改。 提出文档更改的过程在其他方面与以下提出代码更改的过程相同。

要对其余文档（即不显示在https://spark.apache.org/docs/下的文档）提出更改，同样，在spark-website存储库中编辑Markdown并打开拉取请求 。

五、提供用户库到Spark

正如Java和Scala应用程序可以访问大量的库和实用程序一样，它们都不是Java或Scala自身的一部分，Spark旨在支持丰富的库的生态系统。 许多新的有用的实用程序或功能属于Spark之外，而不是在核心。 例如：语言支持可能必须是核心Spark的一部分，但是有用的机器学习算法可以在MLlib之外快乐地存在。

为此，大型和独立的新功能往往被拒绝包含在Spark本身中，但是，可以并应该作为一个单独的项目和存储库托管，并包含在spark-packages.org集合中。

六、贡献的错误报告

理想情况下，错误报告伴随着建议的代码更改以修复错误。 这并不总是可能的，因为那些发现bug的人可能没有经验来解决它。 可以通过创建JIRA但不创建拉取请求来报告错误（见下文）。

但是，如果Bug报告包含足够的信息来理解，隔离和理想地再现错误，它们才有用。 简单地遇到错误并不意味着应该报告错误; 如下所示，首先搜索JIRA并搜索并查询Spark用户/ dev邮件列表。 不可复制的错误或简单的错误报告可能会关闭。

也可以提出新的特征。 这些通常没有帮助，除非伴随细节，例如设计文档和/或代码改变。 大量新文稿应首先考虑spark-packages.org（见上文），或首先在邮件列表中讨论。 功能请求可能会被拒绝，或在长时间不活动后关闭。

七、贡献JIRA维护

考虑到在Apache Spark JIRA中引发的大量问题，不可避免地，一些问题是重复的，或者变得过时，并且最终被固定，否则，或者不能被再现，或者可能从更多细节中受益等。 通过推进讨论或甚至解决JIRA，有助于识别这些问题并解决问题。 大多数贡献者能够直接解决JIRA。 使用判断来确定您是否有信心问题应该解决，虽然可以轻松地撤消更改。 如果有疑问，只要对JIRA发表评论。

在解决JIRA时，请遵守一些有用的约定：

1、Resolve as Fixed如果有变化，您可以指向解决问题

（1）当且仅当解决为固定时，设置修复版本

（2）将受让人设置为对决议贡献最大的人，通常是打开解决问题的公关的人。

（3）如果有几个人贡献，喜欢分配给更多的“初级”，非提交者贡献者

2、对于无法根据报告的主文件复制的问题，请解决为无法重现

     固定也是合理的，如果它清楚什么其他以前的pull请求解决了。 链接到它。

3、如果问题与另一个问题相同或是其他问题的子集，则解决为“重复

（1）确保链接到它重复的JIRA

（2）希望将具有较少活动或讨论的问题解决为副本

（3）如果问题似乎明显过时，并且适用于自打开以来彻底更改的问题或组件，请解决为非问题

4、如果问题没有意义 - 不可操作（例如，非Spark问题），请解析为无效

5、如果这是一个连贯的问题，但有一个明确的迹象表明没有支持或兴趣行事，然后解决为不会修复

6、如果雨伞只是容器问题，不符合自己的可操作更改，则通常会将其标记为已完成

八、准备贡献代码更改

(一)选择要贡献的内容

Spark是一个非常繁忙的项目，平均每几个小时有一个新的JIRA或pull请求。 审查可能需要几个小时或几天的提交者时间。 如果贡献者专注于有用，清晰，易于评估，并已通过基本检查的变更，每个人都会受益。

有时，贡献者已经具有特定的新变化或错误。 如果寻求想法，请参考JIRA中的初始任务列表，或者询问[e-mail]邮件列表。

在进行之前，贡献者应评估所提议的更改是否可能具有相关性，新的和可操作的：

1、是否清楚代码必须改变？ 仅当识别出明确的问题或更改时，建议JIRA和拉取请求才是适当的。 如果只是使用Spark有问题，首先使用邮件列表，而不是考虑提交JIRA或提出更改。 如有疑问，请首先通过电子邮件联系[e-mail]关于可能的更改

2、搜索[e-mail]和[e-mail]邮件列表存档以进行相关讨论。 使用search-hadoop.com或类似的搜索工具。 通常，问题已经讨论过了，一个解决不需要代码更改，或记录什么类型的更改不会被接受为解决。

3、搜索JIRA的现有问题：https://issues.apache.org/jira/browse/SPARK

4、在右上角的搜索框中键入spark [搜索字词]。 如果逻辑上类似的问题已经存在，那么有助于讨论现有的JIRA并首先请求请求，而不是创建一个新的请求。

5、变更的范围是否与提供者的经验水平相匹配？ 任何人都有资格建议打字错误修复，但重构核心调度逻辑需要更多的了解Spark。 一些变化需要先建立经验（见上文）。

九、MLlib特异性贡献指南

1、虽然丰富的算法集是MLLib的一个重要目标，但扩展项目需要首先保持可维护性，一致性和代码质量。 新算法应该：

(1)广为人知
(2)使用和接受（学术引文和具体用例可以帮助证明这一点）
(3)高度可扩展
(4)记录良好
(5)具有与MLLib中的其他算法一致的API来完成同样的事情
(6)有合理期望的开发者支持。
(7)对公共类，方法和变量有@SIS注解。

十、代码审查标准

在考虑如何提供代码之前，了解代码如何审核以及为什么更改可能会被拒绝是有用的。 简单地说，具有许多或大的积极，少数负面影响或风险的变化更有可能被合并，并且被快速合并。 风险和不太有价值的变化不太可能被合并，并且可能被直接拒绝，而不是接受迭代的审查。

1、积极

(1)修复现有功能中的错误的根本原因
(2)添加功能或修复大量用户所需的问题
(3)简单，有针对性
(4)保持或提高Python，Java，Scala的一致性
(5)容易测试; 有测试
(6)降低复杂性和代码行
(7)改变已经被讨论并且是提交者已知的

2、负面，风险

(1)带帮助症状的一个症状
(2)引入复杂的新功能，特别是需要支持的API
(3)增加了复杂性，只帮助一个利基用例
(4)添加不需要在Spark中维护的用户空间功能，但可以外部托管，并由spark-packages.org编制索引
(5)更改公共API或语义（很少允许）
(6)添加大的依赖关系
(7)更改现有依赖关系的版本
(8)添加大量代码
(9)在一个“大爆炸”的变化做了大量的修改

十一、贡献代码更改

请在提出代码更改之前查看上一节。 本节介绍如何操作。

当您提供代码时，您确认该贡献是您的原始工作，并根据该项目的开源许可证将该工作授予该项目。 无论您是否明确声明，通过拉取请求，电子邮件或其他方式提交任何受版权保护的资料，即表示您同意根据项目的开放源代码许可证授权许可该材料，并保证您拥有这样做的法律授权。

1、JIRA

通常，Spark使用JIRA来跟踪逻辑问题，包括错误和改进，并使用Github pull请求来管理特定代码更改的审查和合并。 也就是说，JIRAs用于描述应该修复或更改的内容，高级方法和pull请求描述如何在项目源代码中实现该更改。 例如，主要设计决策在JIRA中讨论。

（1）找到更改涉及的现有Spark JIRA。

a 如果创建一个更改以解决JIRA中的现有问题，请不要创建新的JIRA; 添加到现有的讨论和工作
b 查找从JIRA链接的现有请求，以了解是否有人已在JIRA上工作

（2）如果更改是新的，则通常需要一个新的JIRA。 然而，微小的变化，哪里应该改变，实际上与它应该改变的方式相同，不需要JIRA。 示例：在Foo scaladoc中修复错误

（3）如果需要，创建一个新的JIRA

a 提供描述性标题。 “更新Web UI”或“调度程序中的问题”是不够的。 “Kafka Streaming支持无法处理YARN群集模式下的空队列”是好的。

b 写一个详细的描述。 对于错误报告，这应该理想地包括问题的简短再现。 对于新功能，它可能包括一个设计文档。

c 设置必填字段：

    (a)问题类型。 一般来说，Bug，改进和新特性是Spark中使用的唯一类型。

    (b)优先。 设置为专业或以下; 较高的优先级通常保留给提交者设置。 JIRA往往不幸地在其优先级字段值中混合“大小”和“重要性”。 他们的意思大致：

          阻塞：无意义释放没有这个更改，因为释放将无法使用大量的用户

          关键：大量的用户缺少重要的功能，没有这个，和/或解决方法是困难的

          主要：少数用户缺少重要的功能没有这个，并有一个解决方法

          次要：一个利基用例缺少一些支持，但它不会影响使用或容易解决

          琐事：一个很好的改变，但在实践中不可能有任何问题

d 组件

e 影响版本。 对于Bug，请至少分配一个已知存在问题或需要更改的版本

f  不要设置以下字段：

   (a)修复版本。 这是由提交者分配的，只有当解决。

   (b)目标版本。 这是由提交者分配的，以指示PR已被接受，可能被目标版本修复。

g 不要包括补丁文件; 拉取请求用于提出实际的改变。

（4）如果更改是较大的更改，请考虑在访问[e-mail]时首先讨论此问题，然后再执行更改。

2、拉请求

（1）如果你还没有在Github存储库分支，请访问http://github.com/apache/spark

（2）克隆你的fork，创建一个新的分支，push提交到分支。

（3）考虑文档或测试是否需要作为更改的一部分添加或更新，并根据需要添加它们。

（4）使用./dev/run-tests运行所有测试，以验证代码是否仍然编译，传递测试并通过样式检查。 如果样式检查失败，请查看下面的“代码样式指南”。

（5）对apache / spark的主分支打开拉取请求。 （只有在特殊情况下，PR才能对其他分支机构开放。）

a  PR标题应该是[SPARK-xxxx] [COMPONENT]标题的形式，其中SPARK-xxxx是相关的JIRA号码，COMPONENT是在spark-prs.appspot.com上显示的PR类别之一，标题可以是JIRA的 标题或描述PR本身的更具体的标题。

b 如果pull请求仍然是一个正在进行的工作，所以没有准备好合并，但需要推送到Github以方便审核，然后在组件后添加[WIP]。

c 考虑识别已经改变的代码的提交者或其他贡献者。 在Github中查找文件，然后单击“Blame”以查看最后更改代码的逐行注释。 您可以在PR描述中添加@username，以立即ping它们。

d 请说明该贡献是您的原始工作，并且您根据该项目的开源许可证将该项目的工作许可给该项目

（6）相关的JIRA（如果有）将被标记为“正在进行”，您的拉取请求将自动链接到它。 没有必要是JIRA的受让人来处理它，尽管欢迎您评论您已经开始工作。

（7）Jenkins自动提取请求构建器将测试您的更改

a 如果这是你的第一个贡献，Jenkins将等待确认，然后再构建你的代码，并发布“一个管理员可以验证此补丁吗？

b 提交者可以授权测试使用诸如“ok to test”

c 提交者可以自动允许来自贡献者的未来的拉取请求被测试带有诸如“Jenkins，add to whitelist”的评论，

（8）大约2个小时后，Jenkins会将测试结果发布到pull请求，以及Jenkins的完整结果链接。

（9）注意结果，并及时调查和修复失败

a 修复可以简单地推送到您从中打开您的pull请求的同一个分支

b 当新提交推送时，Jenkins会自动重新测试

c 如果测试由于与更改无关的原因（例如Jenkins中断）而失败，那么提交者可以请求重试“Jenkins，请重新测试”。 询问您是否需要重新启动测试。

(10)审查过程

a 其他审阅者（包括提交者）可能会对更改进行评论，并建议修改。 只需将更多提交推送到同一个分支即可添加更改。

b 鼓励社区中每个人都热烈，礼貌，快速的技术辩论。 结果可能是拒绝整个变化。

c 审阅者可以指示更改看起来适合于与注释合并，例如：“我认为这个补丁看起来不错”。 Spark使用LGTM约定来指示补丁上最强的技术签名级别：只需使用“LGTM”一词进行注释。 它具体意味着：“我已经彻底地看过这个问题，并采取了像我自己写补丁一样多的所有权。 如果您评论LGTM，您将被期望帮助补丁上的错误或后续问题。 一致，明智地使用LGTM是获得作为与更广泛社区的审查者的可信度的一个很好的方式

d 有时，其他更改将被合并，与您的pull请求的更改冲突。 在冲突解决之前，PR不能合并。 这可以使用git fetch origin，然后git merge origin / master解决，并手动解决冲突，然后将结果推送到您的分支。

e 尝试回应讨论，而不是让回答之间的天过去

(11)关闭你的Pull请求/ JIRA

a 如果接受更改，它将被合并，并且拉取请求将自动关闭，以及关联的JIRA（如果有）

  (a)请注意，在极少数情况下，您将被要求打开一个牵引请求，除了master之外的分支，您实际上必须手动关闭拉取请求

  (b)JIRA将被分配给变更的主要贡献者，作为提供信用的方式。 如果JIRA未关闭和/或立即分配，请对JIRA进行注释

b 如果您的提款请求最终被拒绝，请及时关闭

   (a)...因为提交者不能直接关闭PR

   (b)如果提交者发出了“关闭此PR”的注释，大约一个星期后，Apache的自动化过程会自动关闭Pull请求。这意味着提交者特别请求它关闭

c 如果拉取请求很少或没有注意，请考虑改进描述或更改本身，并在几天后再次ping可能的审阅者。 考虑提出更容易包括的更改，例如更小和/或更少侵入性的更改。

d 如果它已经过审查，但在几周后没有被采纳，在从最相关的审阅者征求审查后，或者已经遇到中性反应，结果可以被认为是“软的不”。 

   在这种情况下撤销和关闭公关是有帮助的。

e 如果pull请求关闭，因为它被认为不是解决JIRA的正确方法，那么请保持JIRA打开。 

   但是，如果审查清楚地表明，JIRA中标识的问题不会被任何pull请求解决（不是问题，不会解决），那么还要解决JIRA。

(12)代码样式指南

a 请按照现有代码库的风格。

   (a)对于Python代码，Apache Spark遵循PEP 8，但有一个例外：行的长度最多为100个字符，而不是79个字符。
   (b)对于Java代码，Apache Spark遵循Oracle的Java代码约定。 以下许多Scala指南也适用于Java。
   (c)对于Scala代码，Apache Spark遵循官方Scala样式指南，但具有以下更改。

b 行长度

将行限制为100个字符。 唯一的例外是import语句（尽管即使对于这些语句，尝试将它们保持在100个字符以下）。

c 缩进

一般使用2空间缩进。 对于函数声明，如果参数不适合单个行，则对其参数使用4空格缩进。 例如：

d 代码文档样式

(a)对于在类，对象和方法之前的Scala doc / Java doc注释，使用Java docs样式而不是Scala docs样式。

(b)对于使用代码的内联注释，使用//而不是/ * .. * /。

e import

(a)始终使用绝对路径（例如scala.util.Random）而不是相对路径（例如util.Random）导入包。 此外，按以下顺序排序导入（在每个组中使用字母顺序）：

• java.* and javax.*
• scala.*
• Third-party libraries (org.*, com.*, etc)
• Project classes (org.apache.spark.*)

(b)IntelliJ导入组织器插件可以为您组织导入。 对插件使用此配置（在首选项/编辑器/代码样式/ Scala导入管理器下配置）：

import java.*import javax.* import scala.* import * import org.apache.spark.*

f 中缀法

不要对不是运算符的方法使用中缀符号。 例如，使用list.map（func）代替列表映射func，或者使用string.contains（“foo”）代替string包含“foo”。

 这是为了提高对来自其他语言的开发人员的熟悉程度。

g 大括号

把花括号放在一行if，else或者loop语句中。 唯一的例外是如果你使用if / else作为一行三元运算符。

h 返回值类型

始终在可能的情况下指定方法的返回类型。 如果方法没有返回类型，请根据Scala样式指南指定Unit。 

不需要变量的返回类型，除非定义涉及具有可能不明确的返回值的巨大代码块。

i 如果在怀疑

如果你不确定某种东西的正确风格，请尝试遵循现有代码库的风格。 看看代码中是否有其他使用您的功能的示例。 随时在[e-mail]列表上询问。

注：

JIRA是Atlassian公司出品的项目与事务跟踪工具，被广泛应用于缺陷跟踪、客户服务、需求收集、流程审批、任务跟踪、项目跟踪和敏捷管理等工作领域。