闪电般的统一分析引擎

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

Contributing to Spark doesn’t just mean writing code. Helping new users on the mailing list, testing releases, and improving documentation are also welcome. In fact, proposing significant code changes usually requires first gaining experience and credibility within the community by helping in other ways. This is also a guide to becoming an effective contributor.

因此,本指南组织了各种贡献,以便有意长期参与的新贡献者可以考虑它们. 建立帮助他人的记录,而不只是打开请求请求.

Contributing by Helping Other Users

贡献Spark的一种好方法是帮助在user@spark.apache.org邮件列表或StackOverflow上回答用户问题. 总是有很多新的Spark用户. 花几分钟时间来回答问题是一项非常有价值的社区服务.

贡献者应该订阅此列表并关注它,以便及时了解Spark中发生的事情. 回答问题是帮助社区的一种极好的可见方法,它也显示了您的专业知识.

请参阅邮件列表指南,以获取有关如何有效参与邮件列表以及StackOverflow等论坛的指南.

Contributing by Testing Releases

Spark的发布过程面向社区,社区成员可以在dev@spark.apache.org邮件列表上对新版本进行投票. 邀请Spark用户订阅此列表以接收公告,并测试他们在较新版本上的工作量,并提供有关在较新版本中发现的任何性能或正确性问题的反馈.

Contributing by Reviewing Changes

通过Github拉取请求 (稍后描述)提出,审查和提交对Spark源代码的更改. 任何人都可以在此处查看和评论活动的更改. 审查他人的变更是学习变更过程如何工作并获得代码各个部分活动影响的好方法. 您可以通过检查所做的更改并提出问题或指出问题来提供帮助-像拼写错误或样式问题一样简单. 另请参阅https://spark-prs.appspot.com/,以查看和过滤打开的PR的便捷方法.

Contributing Documentation Changes

要提议对发布文档(即,出现在https://spark.apache.org/docs/下的文档)进行更改,请在Spark的docs/目录中编辑Markdown源文件,其README文件显示了如何在本地构建文档.测试您的更改. 提出文档更改的过程与以下提出代码更改的过程相同.

要对其余文档(即出现在https://spark.apache.org/docs/下的文档)提出更改建议,类似地,在spark-website存储库中编辑Markdown并打开请求请求.

Contributing User Libraries to Spark

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

为此,通常不建议将大型且独立的新功能包含在Spark本身中,但是可以并且应该将其作为单独的项目和资源库托管,并包含在spark-packages.org集合中.

Contributing Bug Reports

理想情况下,错误报告会附有建议的代码更改以修复该错误. 这并非总是可能的,因为发现错误的人可能没有修复该错误的经验. 通过创建JIRA可能会报告错误,但不会创建拉取请求(请参见下文).

错误报告仅在包含足够的信息以理解,隔离和理想地重现错误时才有用. 仅仅遇到一个错误并不意味着应该报告一个错误. 如下所示,搜索JIRA并首先在Spark用户/开发邮件列表中进行搜索和查询. 不可复制的错误或简单的错误报告可能会被关闭.

如果错误报告中有关于错误的引入方式,提交方式的描述,这将非常有帮助,以便审阅者可以轻松地理解错误. 它还可以帮助提交者确定合并合并请求时应向后移植错误修复的距离. 修复错误的请求将问题缩小到根本原因.

性能下降也是一种错误. 修复性能回归的请求必须提供基准,以证明问题确实得到解决.

请注意,数据正确性/数据丢失错误非常严重. 确保相应的错误报告JIRA故障单被标记为correctnessdata-loss . 如果错误报告没有引起足够的关注,请发送电子邮件至dev@spark.apache.org ,以引起更多关注.

也可以提出新功能. 这些通常没有帮助,除非附有详细信息,例如设计文档和/或代码更改. 较大的新贡献应该首先考虑spark-packages.org (请参见上文),或者首先在邮件列表中进行讨论. 长时间不活动后,功能请求可能会被拒绝或关闭.

Contributing to JIRA Maintenance

鉴于Apache Spark JIRA中提出的问题数量巨大,不可避免地有些问题是重复的,或者变得过时并最终以其他方式解决,或者无法重现,或者可以从更多细节中受益,等等. 通过推进讨论甚至解决JIRA,有助于识别这些问题并解决它们,这很有用. 大多数贡献者都可以直接解决JIRA. 尽管可以轻松撤消更改,但要使用判断力来确定您是否很有信心应解决该问题. 如有疑问,请在JIRA上发表评论.

解决JIRA时,请遵守一些有用的约定:

  • 解决为固定,如果有更改,您可以指向该问题已解决
    • 当且仅当分辨率为固定时,设置修订版本
    • 将"受让人"设置为对解决方案贡献最大的人,通常是打开解决该问题的PR的人.
    • 如果有几个人做出了贡献,则希望分配给更"初级"的非贡献者贡献者
  • 对于所报告的无法针对母版复制的问题,请解决为"无法复制"
    • 如果很清楚其他先前的拉取请求已解决该问题,则固定也是合理的. 链接到它.
  • 如果问题与其他问题相同或属于其他问题,则解决为重复
    • 确保链接到重复的JIRA
    • 优先解决活动或讨论较少的问题,将其作为重复项
  • If the issue seems clearly obsolete and applies to issues or components that have changed radically since it was opened, resolve as 没问题
  • 如果问题没有道理-无法解决,例如非火花问题,请解决为无效
  • 如果这是一个连贯的问题,但是有明确的迹象表明对此事没有支持或兴趣,请解决为"不会解决"
  • 如果雨伞仅仅是容器问题,与他们自己的可行变更不符,则经常被标记为"完成"

Preparing to Contribute Code Changes

Choosing What to Contribute

Spark是一个非常繁忙的项目,平均每隔几个小时就会有一个新的JIRA或请求请求. 审核可能要花费数小时或数天的提交时间. 如果贡献者专注于有用,清晰,易于评估且已经通过基本检查的变更,那么每个人都会从中受益.

有时,贡献者已经在脑海中有了一个特定的新变化或错误. 如果要寻求想法,请查阅JIRA中的入门任务列表,或询问user@spark.apache.org邮件列表.

在继续之前,贡献者应评估所提议的变更是否可能是相关的,新的和可行的:

  • 显然代码必须更改吗? 仅当发现明显问题或更改时,才建议JIRA和拉取请求. 如果仅在使用Spark时遇到麻烦,请先使用邮件列表,而不要考虑提交JIRA或提出更改. 如有疑问, user@spark.apache.org首先向user@spark.apache.org发送有关可能的更改的电子邮件
  • 搜索user@spark.apache.orgdev@spark.apache.org邮件列表归档以进行相关讨论. 使用search-hadoop.com或类似的搜索工具. 通常,以前已经讨论过该问题,其解决方案不需要更改代码,或者记录了哪些更改不会被接受为解决方案.
  • 在JIRA中搜索现有问题: https//issues.apache.org/jira/browse/SPARK
  • 在右上角的搜索框中输入spark [search terms] . 如果在逻辑上已经存在类似的问题,则请对现有JIRA进行讨论并首先提出请求,而不是创建一个新请求.
  • 变更的范围是否与贡献者的经验水平相符? 任何人都有资格提出拼写错误建议,但是重构核心调度逻辑需要对Spark有更多的了解. 某些更改需要首先积累经验(请参见上文).

值得再次强调的是,对Spark核心或SQL和Catalyst等高度复杂和重要的模块所做的更改更难于正确地进行. 与更改不太关键的代码相比,它们将受到更多的审查,并受到更高的审查标准.

MLlib-specific Contribution Guidelines

尽管丰富的算法集是MLLib的重要目标,但要扩展项目,则首先需要可维护性,一致性和代码质量. 新算法应:

  • 广为人知
  • 被使用和接受(学术引用和具体用例可以帮助证明这一点)
  • 高度可扩展
  • 有据可查
  • 具有与MLLib中其他可实现相同功能的算法一致的API
  • 带有对开发人员支持的合理期望.
  • Have @Since annotation on public classes, methods, and variables.

Code Review Criteria

在考虑如何贡献代码之前,了解如何审查代码以及为什么更改可能被拒绝很有用. 请参阅Google工程实践文档中有关代码审阅者详细指南 . 简而言之,具有很多或大的积极影响而很少有消极影响或风险的变更很可能会被合并并迅速合并. 风险较小且价值较小的更改极不可能被合并,并且可能会被直接拒绝,而不是接受反复审核.

Positives

  • 修复了现有功能中的错误的根本原因
  • 添加功能或解决大量用户所需的问题
  • 简单,针对性
  • 维护或改善Python,Java,Scala的一致性
  • 易于测试; 有测试
  • 减少复杂性和代码行
  • 变更已经讨论过,提交者知道

Negatives, Risks

  • 创可贴仅是错误的症状
  • 引入了复杂的新功能,尤其是需要支持的API
  • 增加仅有助于利基用例的复杂性
  • 添加不需要在Spark中维护但可以在外部托管并由spark-packages.org编制索引的用户空间功能
  • 更改公共API或语义(极少允许)
  • 增加大的依赖性
  • 更改现有依赖项的版本
  • 添加大量代码
  • 在一次"大爆炸"变更中进行了大量修改

Contributing Code Changes

建议更改代码之前,请先阅读上一节. 本节介绍如何执行此操作.

当您贡献代码时,您确认该贡献是您的原始工作,并且您已根据项目的开源许可证将工作许可给该项目. 不论您是否明确声明,通过拉取请求,电子邮件或其他方式提交任何受版权保护的材料,都表示您同意根据项目的开源许可对材料进行许可,并保证您具有这样做的合法权力.

Cloning the Apache Spark source code

如果您有兴趣使用最新的未开发代码或对Apache Spark开发有所帮助,则可以从Git签出master分支:

# Master development branch
git clone git://github.com/apache/spark.git

下载Spark之后,您可以在文档页面上找到安装和构建它的说明 .

JIRA

通常,Spark使用JIRA跟踪逻辑问题,包括错误和改进,并使用Gi​​thub拉取请求来管理特定代码更改的审阅和合并. 也就是说,JIRAs被用来描述应该是固定的或变化,高层次的方法,并引入请求介绍如何实现在项目的源代码的变化. 例如,JIRA中讨论了主要的设计决策.

  1. 查找与更改有关的现有Spark JIRA.
    1. 如果创建更改以解决JIRA中的现有问题,请不要创建新的JIRA; 添加到现有讨论中并改为工作
    2. 查找从JIRA链接的现有拉取请求,以了解是否有人已经在JIRA上工作
  2. 如果更改是新的,则通常需要新的JIRA. 但是,琐碎的更改(实际上应该更改的内容与应该更改的内容相同)不需要JIRA. 示例: Fix typos in Foo scaladoc
  3. 如果需要,创建一个新的JIRA:
    1. 提供描述性标题. "更新Web UI"或"计划程序中的问题"还不够. " Kafka Streaming支持无法在YARN群集模式下处理空队列"很好.
    2. 写一个详细的描述. 对于错误报告,理想情况下应简短地再现问题. 对于新功能,它可能包括设计文档.
    3. 设置必填字段:
      1. 问题类型 . 通常,错误,改进和新功能是Spark中使用的唯一类型.
      2. 优先权 . 设为专业或以下; 通常,较高的优先级留给提交者设置. 主要例外是正确性或数据丢失问题,可以将其标记为阻止程序. 不幸的是,JIRA倾向于将其"优先级"字段值中的"大小"和"重要性"混合在一起. 它们的含义大致为:
        1. 阻止程序:如果没有此更改,则无济于事,因为该发行版将对绝大多数用户不可用. 正确性和数据丢失问题应视为阻止程序.
        2. 严重:没有这个功能,一小部分用户会丢失重要功能,并且/或者变通办法很困难
        3. 重大:少数用户在缺少此功能的情况下会丢失重要功能,因此有一种解决方法
        4. 轻微:小众用例缺少一些支持,但不影响使用或易于解决
        5. 琐碎:不错的更改,但实际上不太可能出现任何问题
      3. 零件
      4. 影响版本 . 对于错误,请至少分配一个已知存在问题或需要更改的版本
      5. 标签 . 除以下方面外,未被广泛使用:
        • correctness :正确性问题
        • data-loss :数据丢失问题
        • release-notes :变更的影响需要在发行说明中提及. JIRA或拉取请求应包含适合包含在发行说明中的​​详细信息–请参阅下面的"文档文本".
        • starter :小巧,简单的更改适合新​​贡献者
      6. 文档文本 :对于需要在发行说明中输入内容的问题,此信息应包含发行管理器应在发行说明中包含的信息. 这应该包括对受影响的行为的简短摘要,以及有关更改的行为的详细信息. 打开JIRA时可以临时填写,但解决问题后可能需要使用最终详细信息进行更新.
    4. 不要设置以下字段:
      1. 修复版本 . 仅在解决时由提交者分配.
      2. 目标版本 . 由提交者分配,以指示目标版本已接受PR进行可能的修复.
    5. 不包括补丁文件; 拉取请求用于建议实际更改.
  4. 如果更改是一个大更改,请考虑在继续实施更改之前首先邀请dev@spark.apache.org问题进行讨论.

Pull Request

  1. 如果您尚未在Github存储库中分叉 https://github.com/apache/spark
  2. 克隆您的fork,创建一个新分支,将提交推送到该分支.
  3. 考虑是否需要在变更中添加或更新文档或测试,并根据需要添加它们.
    1. 添加测试时,请确保测试具有自我描述性.
    2. 另外,当拉取请求旨在解决特定问题时,您应该考虑在测试中写入JIRA ID. 实际上,通常是在JIRA类型为错误或PR将两个测试添加到现有测试类时添加. 请参阅以下示例:
      • 斯卡拉
         test("SPARK-12345: a short description of the test") { ... 
      • 爪哇
         @Test public void testCase() { // SPARK-12345: a short description of the test ... 
      • 蟒蛇
         def test_case(self): # SPARK-12345: a short description of the test ... 
      • [R
         test_that("SPARK-12345: a short description of the test", { ... 
  4. 使用./dev/run-tests运行所有测试,以验证代码仍在编译,通过测试并通过样式检查. 如果样式检查失败,请查看下面的《代码样式指南》.
  5. 针对apache/sparkmaster分支打开拉取请求 . (仅在特殊情况下,才对其他分支机构开放公关.)
    1. PR标题应采用[SPARK-xxxx][COMPONENT] Title ,其中SPARK-xxxx是相关的JIRA编号, COMPONENTspark-prs.appspot.com中显示的PR类别之一 ,标题可能是JIRA的标题或描述PR本身的更具体的标题.
    2. 如果拉取请求仍在进行中,因此尚未准备好进行合并,但需要将其推送到Github以便于审核,然后在组件后添加[WIP] .
    3. 考虑确定已经处理了要更改的代码的提交者或其他贡献者. 在Github中找到文件,然后单击"责备"以逐行注释谁最后一次更改了代码. 您可以在PR描述中添加@username以立即对其进行ping操作.
    4. 请声明所做的贡献是您的原始作品,并且您已根据项目的开源许可证将作品许可给该项目.
  6. 相关的JIRA(如果有)将被标记为"进行中",并且您的拉取请求将自动链接到它. 尽管欢迎您评论您已开始工作,但无需JIRA的受让人即可进行工作.
  7. Jenkins自动提取请求构建器将测试您的更改
    1. 如果这是您的第一个贡献,Jenkins将在构建代码之前等待确认并发布"其中一位管理员可以验证此补丁吗?"
    2. 提交者可以使用"可以测试"之类的评论授权测试
    3. 提交者可以自动允许来自贡献者的将来拉取请求进行测试,例如"詹金斯,添加到白名单"
  8. 大约2小时后,Jenkins会将测试结果发布到拉取请求中,并提供指向Jenkins上完整结果的链接.
  9. 注意结果,并迅速调查并修复故障
    1. 可以简单地将修订推入您打开拉取请求的同一分支
    2. 当推送新的提交时,Jenkins将自动重新测试
    3. 如果测试由于与更改无关的原因而失败(例如,詹金斯(Jenkins)断电),则提交者可以请求"詹金斯,请重新测试"进行重新测试. 询问是否需要重新启动测试. 如果您之前是由提交者"詹金斯,添加到白名单"添加的,则您还可以要求重新测试.
  10. 如果您的拉取请求中有与SparkR相关的更改,AppVeyor将被自动触发以在Windows上测试SparkR,大约需要一个小时. 与上述步骤类似,修复故障并推送新的提交,这将要求在AppVeyor中进行重新测试.

The Review Process

  • Other reviewers, including committers, may comment on the changes and suggest modifications. Changes can be added by simply pushing more commits to the same branch.
  • 社区中的每个人都应进行生动,礼貌,快速的技术辩论. 结果可能是拒绝整个更改.
  • 请记住,对Spark的更关键部分的更改(例如其核心和SQL组件)将受到更多审核,并且与其他更改相比,可能需要更多测试和证明其正确性.
  • 审阅者可以指出更改看起来适合与评论合并,例如:"我认为此补丁看起来不错". Spark使用LGTM约定来指示补丁程序中最强的技术签名级别:只需用" LGTM"一词注释即可. 它的具体含义是:"我已经仔细研究过,并拥有与我自己编写补丁一样多的所有权". 如果您对LGTM发表评论,我们将为您解决补丁程序中的错误或后续问题. 一致,明智地使用LGTM是在广大社区中作为审阅者赢得信誉的绝佳方法.
  • 有时,其他更改会与您的拉取请求的更改冲突. 在解决冲突之前,无法合并PR. 可以通过以下方法解决此问题,例如,通过添加远程以跟上git remote add upstream https://github.com/apache/spark.git ,运行git fetch upstream然后git rebase upstream/master并解决手动冲突,然后将结果推送到您的分支.
  • 尝试对讨论做出回应,而不是让回复之间隔几天

Closing Your Pull Request / JIRA

  • 如果更改被接受,它将被合并并且拉取请求将自动关闭,并且相关联的JIRA(如果有)
    • 请注意,在极少数情况下,系统会要求您针对master以外的分支打开请求请求,实际上您实际上必须手动关闭请求请求
    • JIRA将被分配给更改的主要贡献者,以作为一种奖励方式. 如果未立即关闭和/或立即分配JIRA,请对JIRA进行评论.
  • 如果您的拉取请求最终被拒绝,请立即将其关闭
    • …因为提交者无法直接关闭PR
    • 如果提交者发表了诸如"请注意关闭此PR?"之类的评论,则将在一周后由Apache的自动化流程自动关闭拉取请求.这意味着提交者明确要求关闭它.
  • 如果请求请求很少或根本没有引起注意,请考虑改进描述或更改本身,并在几天后再次ping通可能的审阅者. 考虑提出一个更容易包含的更改,例如较小和/或侵入性较小的更改.
  • If it has been reviewed but not taken up after weeks, after soliciting review from the most relevant reviewers, or, has met with neutral reactions, the outcome may be considered a “soft no”. It is helpful to withdraw and close the PR in this case.
  • 如果关闭请求是因为认为解决JIRA的方法不正确,则将JIRA保持打开状态. 但是,如果审查明确表明JIRA中标识的问题将不会通过任何拉取请求解决(不是问题,将无法解决),则也可以解决JIRA.

Code Style Guide

请遵循现有代码库的样式.

  • 对于Python代码,Apache Spark遵循PEP 8 ,但有一个例外:每行最多可以包含100个字符,而不是79个字符.
  • 对于R代码,Apache Spark遵循Google的R样式指南 ,但有以下三个例外:行的长度最多可以为100个字符,而不是80个字符,函数名称没有限制,但是其首字母小写,并且允许使用S4对象/方法.
  • 对于Java代码,Apache Spark遵循下面的Oracle Java代码约定和Scala准则. 后者是优选的.
  • 对于Scala代码,Apache Spark遵循官方的Scala样式指南Databricks Scala指南 . 后者是优选的. 要格式化Scala代码,请在提交PR之前运行./dev/scalafmt.

If in Doubt

如果您不确定某种样式的正确性,请尝试遵循现有代码库的样式. 查看代码中是否还有其他示例使用您的功能. 也可以在dev@spark.apache.org列表上询问和/或询问提交者.

by  ICOPY.SITE