导致火花| Apache火花 -

本指南文件最好的方法使Apache火花,各种类型的贡献包括之前需要提交代码更改。

导致火花并不仅仅意味着编写代码。帮助新用户邮件列表,测试版本,提高文档也欢迎。事实上,提出重要的代码更改通常需要先积累经验和信誉在社区内以其他方式帮助。这也是一个引导成为一个有效的贡献。

这引导组织的贡献,以便他们应该考虑新的贡献者打算长期参与。构建一些帮助别人的记录,而不是打开拉请求。

通过帮助其他用户

导致火花的好办法是帮助回答用户的问题user@www.leiyimei360.com邮件列表或StackOverflow。总是有很多新的火花用户;花几分钟来回答一个问题是一个非常有价值的社区服务。

贡献者应该订阅这个列表并遵循它为了赶上时代潮流发生了什么火花。回答问题是一个很好的和可见的方式来帮助社区,也展示了你的专业知识。

看到邮件列表指南指导如何有效地参与讨论邮件列表,以及像StackOverflow论坛。

为测试版本

火花的发布过程是社区,社区成员可以投票在新版本dev@www.leiyimei360.com邮件列表。引发用户邀请订阅这个列表接收公告,新版本和测试他们的工作负载,提供反馈在任何性能或正确性问题在新版本中找到。

通过回顾修改贡献

火花源代码提出变更,审核并通过GitHub的请求(稍后介绍)。任何人都可以查看和评论在这里积极变化。检查别人的变化是一个很好的学习方式改变的过程是如何工作的,并获得接触活动代码的各个部分。你可以帮助检查更改并提问或指出问题,简单的拼写错误或小问题的风格。另请参阅https://spark-prs.appspot.com/一个方便的方式来查看和过滤器PRs开放。

文档修改贡献

提出更改释放文档(文档下出现的//www.leiyimei360.com/docs/),在火花源文件编辑减价的文档/目录的自述本地文件显示了如何构建文档来测试您的更改。流程提出医生改变否则一样的过程提出了下面的代码更改。

提出改变文档(即文档的其余部分不出现在//www.leiyimei360.com/docs/),同样的,编辑的减价spark-website库和打开一个请求。

造成用户库火花

就像Java和Scala应用程序可以访问一个巨大的选择的库和工具,其中没有一个是Java或Scala本身的一部分,火花旨在形成一个丰富的生态系统,库的支持。许多新的有用的实用程序或功能属于外部的火花,而不是核心。例如:语言支持可能是核心火花的一部分,但是,有用的机器学习算法可以幸福MLlib之外的存在。

为此,大的和独立的新功能往往是拒绝列入火花本身,但是,可以而且应该被托管作为一个单独的项目和存储库,并包含在spark-packages.org收集。

造成错误报告

理想的情况是,伴随着bug报告提出修复bug的代码更改。这并不总是可能的,那些发现一个bug可能没有经验来解决它。错误可能是通过创建一个报告JIRA但没有创建一个请求(见下文)。

Bug报告仅仅是有用的但是如果他们包含足够的信息来理解,隔离和理想情况下重现Bug。只是遇到一个错误并不意味着一个错误应该报道;如下所示,搜索JIRA和搜索和查询引发用户/ dev邮件列表。Unreproducible bug,或者简单的错误报告,可能被关闭。

很有帮助,如果错误报告介绍了如何描述错误,提交的,所以评论者可以很容易地理解错误。它还帮助提交者来决定应该如何补丁目前bug修复,当拉请求合并。拉请求修复bug应该缩小问题的根本原因。

性能回归也是一种错误。拉请求修复性能回归必须提供一个基准来证明这个问题确实是固定的。

注意,数据正确性/数据丢失错误是非常严重的。确保JIRA票贴上相应的bug报告正确性或数据丢失。如果错误报告并没有得到足够的重视,请发送电子邮件dev@www.leiyimei360.com吸引更多的关注。

可以提出新的功能。这些通常不会有帮助,除非伴随着细节,比如设计文档和/或代码更改。应该考虑大新的贡献spark-packages.org第一次(见上图),或者在邮件列表上讨论。特性请求可能会被拒绝,或关闭经过一段长时间的不活动。

导致JIRA维护

鉴于Apache大量问题引发JIRA,不可避免地有一些问题重复,或过时,并最终固定否则,或不能复制,或可能受益更多细节,等等。是有用的帮助识别和解决这些问题,通过推进甚至解决JIRA的讨论。大多数贡献者能够直接解决jira。使用的判断决定是否你很自信这个问题应该解决,尽管变化可以轻易消除。如果有疑问,JIRA上留下评论。

当解决jira,看到一些有用的约定:

解决,固定如果有改变你可以解决这个问题
- 修复版本(s),当且仅当该决议是固定的
- 设置受让人最有贡献的人解决,通常的人打开了公关,解决了问题。
- 几个人了,宁愿分配“初级”越多,non-committer贡献者
对主问题不能重现报道,解决不能复制
- 固定是合理的,如果它是清楚其他之前把请求解决它。链接到它。
如果问题是一样的或另一个问题的一个子集,是解决重复的
- 确保链接JIRA副本
- 喜欢解决问题,更少的活动或讨论重复
如果这个问题看起来显然过时和适用于问题或组件,已经发生了根本性的变化,因为它是打开,解决不是一个问题
如果这个问题没有意义——不是可行的,例如,一个non-Spark问题,解决无效的
如果它是一个连贯的问题,但有一个清楚地表明,没有支持或表演的兴趣,然后解决无法解决
雨伞经常标记完成如果他们只是容器的问题不对应一个可操作的改变自己的

准备贡献代码更改

选择什么做出贡献

火花是一个异常忙碌的项目,一个新的JIRA或拉请求平均每隔几个小时。审查提交者可以几小时或几天的时间。每个人都好处如果贡献者关注变化,是有用的,清晰,容易评估,基本已经通过检查。

有时,一个贡献者将已经有一个特定的新的变更或错误。如果寻求想法,请咨询JIRA启动任务的列表,或要求user@www.leiyimei360.com邮件列表。

在继续之前,贡献者应该评估如果拟议的改变可能是相关的,新的和可操作的:

清晰的代码必须改变吗?提出JIRA拉请求适当的只有一个明确的问题或改变已被确认。如果只是难以使用火花,首先使用邮件列表,而不是考虑申请一个JIRA或提议的改变。有疑问时,电子邮件user@www.leiyimei360.com第一个可能的变化
搜索user@www.leiyimei360.com和dev@www.leiyimei360.com邮件列表档案相关讨论。通常,问题讨论,决议,不需要一个代码的变化,或记录什么样的变化将不会接受一项决议。
JIRA搜索现有的问题:https://issues.apache.org/jira/browse/SPARK
类型[关键词]火花在右上角的搜索框。如果已经存在一个逻辑上类似的问题,那么为首先讨论现有JIRA和拉请求,而不是创建一个新的。
变化的范围匹配因素的水平的经验吗?任何人都有资格提出错误修复,但重构核心调度逻辑需要更多的理解火花。一些变化需要积累经验(见上图)。

值得重新强调变化引发的核心,或高度复杂和重要模块如SQL和催化剂,更难以正确。他们将受到更严格的审查,承担审查标准高于变化较少的关键代码。

MLlib-specific贡献指南

虽然一组丰富的算法是一个重要的目标MLLib,扩展项目要求可维护性、一致性和代码质量放在首位。新算法:

被广泛知道
使用和接受(学术引用和具体的用例可以帮助调整)
是高度可伸缩的
是有据可查的
在MLLib api一致的与其他算法,实现相同的事
有一个合理的期望开发人员支持。
有@Since注释在公共类、方法和变量。

错误消息的指导方针

火花应该抛出异常与标准化和可操作的错误消息。

错误消息应该回答下列问题:

什么是这个问题吗?
为什么问题发生吗?
如何这个问题可以解决吗?

写错误信息时,你应该:

使用主动语态
避免基于时间的语句,例如承诺未来的支持
使用现在时态来描述错误,并提供建议
提供具体的例子如果决议尚不清楚
避免听起来指责,评判,或者侮辱
是直接
不要使用编程术语中面向用户的错误吗

看到错误消息的指导方针为更多的细节。

代码评审标准

在考虑如何贡献代码,是有用的了解代码审查,以及为什么变化可能被拒绝。看到详细的指南代码评审从谷歌的工程实践文档。简单地说,有很多的变化,或大优点,和一些负面影响或风险,更有可能被合并,合并后的迅速。风险和价值的变化很可能被合并,并可能被直接驳回,而不是接受迭代的审查。

阳性

修复一个缺陷的根源在现有功能
增加功能或修复一个问题需要通过大量的用户
简单,有针对性的
保持或提高一致性Python, Java, Scala
容易测试;已经测试
降低复杂性和行代码
改变已经讨论和提交者

底片、风险

创可贴bug的征兆
介绍了复杂的新功能,特别是需要支持的API
增加了复杂性,只有帮助一个利基的用例
增加了用户空间功能,不需要维护在火花,但可以承载外部和索引spark-packages.org
改变一个公共API或语义(很少允许)
增加大的依赖性
改变现有版本的依赖关系
增加了大量的代码
使大量的修改在一个“大爆炸”的变化

贡献代码更改

前请检查前一节提出一个代码变化。本节文档如何这样做。

贡献代码时,您肯定贡献你的原创作品,并且您许可的工作项目在项目的开放源码许可。你们国家是否明确,通过将请求提交任何受版权保护的材料,电子邮件,或者其他方式你同意许可项目的开源许可下的材料和保证你的合法权力。

克隆Apache火花™源代码

如果你有兴趣使用最新的开发代码或导致Apache火花发展,你可以查看从Git主分支:

#主开发分支git克隆git: / /github.com/apache/spark.git

一旦你下载的火花,你可以找到指导安装和建筑上文档页面。

JIRA

一般来说,火花使用JIRA跟踪逻辑问题,包括错误和改进,并使用GitHub拉请求管理特定代码更改的评审和合并。也就是说,jira用于描述什么应固定或变化,和高级方法,并把请求描述如何实现这一变化在项目的源代码。例如,JIRA的主要设计决策进行了讨论。

发现现有火花JIRA的变化有关。
1. 不创建一个新的JIRA如果创建一个改变在JIRA解决现有问题;添加到现有的讨论和工作
2. 寻找现有拉请求从JIRA联系,了解如果有人已经JIRA上工作
如果改变是新的,那么它通常需要一个新的JIRA。然而,微不足道的变化,该变化是几乎一样的它应该如何改变不需要JIRA。例子:修复在Foo scaladoc拼写错误
如果需要,创建一个新的JIRA:
1. 提供一个描述性的标题。“web UI更新”或“问题”在调度器是不够的。“卡夫卡流支持未处理空纱集群中的队列模式”是好的。
2. 写一个详细的描述。对于bug报告,这应该包括一个简短的生殖问题。对于新功能,它可能包括一个设计文档。
3. 设置必需的字段:
  1. 问题类型。一般来说,缺陷,改进和新特性是唯一类型用于火花。
  2. 优先级。设置为主要或以下;更高的优先级通常是保留给提交者集。主要的例外是正确性或数据丢失问题,可以标记为阻滞剂。JIRA往往不幸混淆“大小”和“重要性”的优先级字段值。他们的大致意思是:
    1. 拦截器:无意义的释放没有这个变化释放大少数的用户将无法使用。正确性和数据丢失问题应考虑阻滞剂的目标版本。
    2. 关键:很大一部分用户错过了重要的没有这个功能,和/或解决方案是很困难的
    3. 主要:一小部分用户没有这个缺失的重要功能,有一个解决方案
    4. 小:用例是失踪的一些支持,但它不影响使用或很容易工作
    5. 简单:可有可无的变化但不太可能有任何问题在实践中并非如此
  3. 组件
  4. 影响版本。错误,至少分配一个版本被展览问题或需要改变
  5. 标签。不被广泛使用,除了以下:
    - 正确性:一个正确性问题
    - 数据丢失:一个数据丢失的问题
    - 发布说明:在发布说明变化的影响需要提及。JIRA或拉请求应包括详细适用于包含在发布说明,请参见下面的“文本文档”。
    - 起动器:小,简单改变适合新的贡献者
  6. 文档的文本:在发布说明问题,需要一个条目,这个应该包含的信息发布经理应该包括发行说明。这应该包括一个简短的摘要的行为的影响,和细节的行为改变。它可以暂时填写JIRA打开时,但可能需要更新最终的细节问题得到解决。
4. 不设置以下字段:
  1. 修复版本。这是由提交者只有在解决。
  2. 目标版本。这是由提交者指出公关已被接受为可能的解决目标版本。
5. 不包括一个补丁文件;把请求用于提出实际的改变。
如果是一个很大的改变,考虑邀请讨论这个问题dev@www.leiyimei360.com首先在继续之前实现改变。

把请求

之前创建一个请求在Apache火花,重要的是要检查测试是否可以通过在你的部门,因为我们的GitHub操作工作流自动运行测试后你把请求/提交和每次运行负担GitHub行为的有限的资源在Apache火花库。下面的步骤将引导你完成这一过程。

叉在GitHub库https://github.com/apache/spark如果你没有了
转到“行动”选项卡在你的分叉的库,使“构建和测试”和“报告测试结果”工作流
克隆你的叉和创建一个新的分支
考虑文档或测试是否需要添加或更新的变化,并根据需要添加它们。
1. 当您添加测试,确保测试是自描述的。
2. 同时,你应该考虑编写JIRA ID在测试当你把请求目标解决特定的问题。在实践中,通常是添加当JIRA类型错误或公关增加了几个测试现有的测试类。看下面的例子:
  - Scala
    测试(“火星- 12345:一个简短的描述测试”){…
  - Java
    @Test公共空testCase(){/ /火花- 12345:一个简短的描述测试的…
  - Python
    def test_case(自我):#火花- 12345:一个简短的描述测试的…
  - R
    test_that(“火星- 12345:一个简短的描述的测试”,{…
考虑基准测试结果是否应该添加或更新的变化,并根据需要添加它们在分叉的存储库运行基准测试生成基准测试结果。
运行所有测试,,/ dev /运行测试验证代码编译,通过测试,通过风格检查。如果风格检查失败,检查下面的代码风格指南。
将提交你的分支。这将触发“构建和测试”和“报告测试结果”工作流分叉的存储库并开始测试和验证您的更改。
打开一个拉请求对主的分支apache /火花。(只有在特殊情况下的公关会打开对其他分支)。这将触发工作流”拉请求*”(火花回购)/观察寻找成功的工作流运行在“你”分叉的存储库(它会等待如果运行)。
1. 公关的标题应该的形式[SPARK-xxxx](组件)标题,在那里SPARK-xxxx是有关JIRA的数字,组件是一个公关类别显示在哪里spark-prs.appspot.com和标题可能JIRA的标题或描述公关本身更具体的标题。
2. 如果把请求仍然是一个正在进行的工作,所以还没有准备好被合并,但需要推到GitHub便于复习,然后添加(在制品)后的组件。
3. 考虑确定提交者或其他贡献者的代码更改。找到文件在GitHub (s),单击“责怪”看到逐行注释谁改变了代码。您可以添加@用户名在公关描述萍。
4. 请贡献你的原创作品,并且您许可的工作项目在项目的开放源码许可。
相关JIRA(如果有的话)将标记为“进步”和你的请求将自动链接到它。没有需要的受让人JIRA工作,虽然你是受欢迎的评论,你已经开始工作。
如果有改变你拉SparkR有关的请求时,将自动触发AppVeyor测试SparkR在Windows上,这需要大约一个小时。类似于上面的步骤中,修复失败和推动新提交AppVeyor将请求重新测试。

评审过程

其他评论家,包括提交者,评论更改并建议修改。变化可以通过将添加更多提交相同的分支。
活泼、有礼貌、快速技术鼓励辩论从社区中。结果可能是整个变化的拒绝。
记住,改变引发的关键部分,其核心和SQL组件,将受到更严格的审查,并且可能需要比其他更改测试和证明其正确性。
评论者可以表明改变看起来适合合并一个评论,如:“我认为这片看起来不错”。火花使用LGTM公约表明技术批准一个补丁的最高水平:简单的评论“LGTM”这个词。它具体的意思是:“我看着这彻底,把尽可能多的所有权如果补丁是我自己写的”。如果你评论LGTM将帮助bug补丁或后续问题。一致的,明智地使用LGTMs是一个伟大的方式来获得信誉作为评论家与更广泛的社区。
有时,其他更改将被合并冲突与你把请求的更改。公关不能合并,直到冲突解决。这可以解决,例如,添加一个远程上游跟上变化git远程上游添加https://github.com/apache/spark.git,运行git获取上游紧随其后的是git变基上游/主人和解决冲突,然后把结果你的分支。
试图能够响应之间的讨论而不是让天通过回答

闭拉请求/ JIRA

如果更改被接受,它将合并,把请求将自动关闭,随着JIRA如果有任何关联
- 请注意,在罕见的情况下,你被要求打开一个拉请求对另外一个分支主,你会不得不关闭手动拉请求
- JIRA将分配给主因素变化给予信贷的一种方式。如果JIRA没有及时关闭和/或分配,JIRA上发表评论。
如果你把最终拒绝了请求,请立即关闭它
- …因为委托人不能直接关闭PRs
- 把请求将被自动关闭一个自动化的过程在Apache大约一周后如果一个提交者做出了评论,像“关闭这个公关吗?“这意味着提交者是专门要求它被关闭。
如果把请求已经很少或根本没有注意,考虑提高描述或改变本身和萍可能几天后再次评审。考虑提议的改变容易包括,像一个小和/或侵入性较小的变化。
如果它已经回顾了但不了几周后,从最相关的评论者征求评论后,或者,会见了中性反应,结果可能被视为一个“软”。退出并关闭公关是有帮助的。
如果把请求关闭,因为它被认为是不正确的方法来解决JIRA,然后把JIRA开放。但如果审查表明JIRA中标识的问题是不会解决任何拉请求(不是问题,无法解决),那么也解决JIRA。

代码风格指南

请跟现有的代码库的风格。

对于Python代码,Apache火花PEP 8但有一个例外:线路可达100个字符长度,而不是79年。
R代码,Apache火花谷歌的R风格指南有三个例外:线路可达100个字符长度,不是80,没有限制函数名但它有一个最初的小写后者和S4对象/方法是允许的。
对于Java代码,Apache火花甲骨文Java代码约定和Scala下面的指导方针。后者是首选。
Scala代码,Apache火花遵循官方Scala风格指南和砖Scala的指南。后者是首选。格式Scala代码,运行。/ dev / scalafmt之前提交公关。

如果有疑问

如果你不确定正确的风格的东西,尽量遵循现有的代码库的风格。看看是否有其他的例子的代码中使用你的特性。请提出来的dev@www.leiyimei360.com列表和/或要求提交者。

的行为准则

Apache项目遵循火花Apache软件基金会的行为准则。的的行为准则适用于所有空间由Apache软件基金会管理,包括IRC,所有公共和私人邮件列表,问题跟踪器,维基、博客、Twitter和其他我们的社区使用的通信通道。的行为准则,是特定于面对面的事件(即。、会议)编纂的ASF发表反骚扰政策。

我们预计这段代码的行为被人荣幸参与Apache社区正式或非正式地,或声称任何基金会的归属,无论我会提及一些与基金会相关的活动,特别是当代表ASF,在任何角色。

这段代码不详尽或完成。它提炼我们共同了解协作,共享环境和目标。我们期望它遵循的精神在信中,这样它可以丰富我们的人生和技术社区的参与。

和具体的指导方针的更多信息,请参考Apache软件基金会的行为准则。