投稿人指南

如果你正在阅读这篇文章,你可能会对请求的贡献感兴趣。非常感谢你!开源项目的生存和消亡是基于他们从其他人那里得到的支持,而事实上,你甚至在考虑为请求项目做出贡献 very 你真大方。

本文件列出了对本项目作出贡献的指导方针和建议。如果你想做贡献,请先阅读本文档并了解如何为这个项目做出贡献。如果您有任何问题,请随时联系 Nate PrewittIan CordascoSeth Michael Larson 主要维护人员。

本指南根据您考虑的贡献类型分为多个部分,其中一个部分涵盖了所有贡献者的一般指导原则。

亲切

热情点,或者在路上。. -肯尼斯·雷茨

请求有一个非常重要的规则来管理所有形式的贡献,包括报告错误或请求特性。这条黄金法则是” be cordial or be on your way “。

欢迎所有的贡献, 只要涉及到的每个人都受到尊重。

获得早期反馈

如果你在做贡献,不要觉得有必要坐在你的贡献上,直到它被完美地打磨和完善。这有助于所有相关人员尽早寻求反馈。提交一份早期的、未完成的稿件作为反馈,绝不会损害你接受稿件的机会,也可以避免你将大量工作投入到不适合项目的稿件中。

贡献适宜性

我们的项目维护人员对贡献是否适合请求有最后一句话。所有捐款将被仔细考虑,但有时,捐款将被拒绝,因为他们不符合当前的目标或项目的需要。

如果你的贡献被拒绝了,不要绝望!只要你遵守这些准则,你就有更好的机会让你的下一份贡献被接受。

代码贡献

提交代码的步骤

当贡献代码时,您需要遵循以下清单:

  1. 在Github上复刻存储库。

  2. 运行测试以确认它们都通过您的系统。如果他们不这样做,你就需要调查他们失败的原因。如果您自己无法诊断此问题,请按照本文档中的指南将其作为错误报告提出: 错误报告 .

  3. 编写测试来演示您的bug或特性。确保他们失败。

  4. 做你的改变。

  5. 再次运行整个测试套件,确认所有测试都通过 包括你刚加的那些.

  6. 向主存储库发送Github Pull请求 master 分支机构。Github Pull请求是此项目上预期的代码协作方法。

下面的小节将详细介绍上面的一些要点。

代码审查

只有经过代码审查,才能合并贡献。除非您强烈反对,否则您应该实现任何代码评审反馈。如果您反对代码审查反馈,您应该清楚、冷静地提出您的理由。如果在这样做之后,认为反馈仍然适用,您必须应用反馈或撤回您的贡献。

新参与者

如果您是新的或对开源相对较新的,欢迎!请求旨在温和地介绍开放源码的世界。如果您关心如何最好地做出贡献,请考虑邮寄维护人员(如上所列)并寻求帮助。

请同时检查 获得早期反馈 部分。

Kenneth Reitz的代码风格™

请求代码库使用 PEP 8 代码风格。

除了PEP 8中概述的标准外,我们还有一些指导方针:

  • 行长度可以超过79个字符,到100个,如果方便的话。

  • 行长度可以超过100个字符,否则 terribly 不方便。

  • 始终使用单引号字符串(例如 '#flatearth' ,除非字符串中出现单引号。

另外,PEP8推荐的款式之一 line continuations 完全缺乏品味,不允许在请求代码库中使用:

# Aligned with opening delimiter.
foo = long_function_name(var_one, var_two,
                         var_three, var_four)

不。不要。求你了。这样好多了:

foo = long_function_name(
    var_one,
    var_two,
    var_three,
    var_four,
)

docstring将遵循以下语法:

def the_earth_is_flat():
    """NASA divided up the seas into thirty-three degrees."""
    pass
def fibonacci_spiral_tool():
    """With my feet upon the ground I lose myself / between the sounds
    and open wide to suck it in. / I feel it move across my skin. / I'm
    reaching up and reaching out. / I'm reaching for the random or
    whatever will bewilder me. / Whatever will bewilder me. / And
    following our will and wind we may just go where no one's been. /
    We'll ride the spiral to the end and may just go where no one's
    been.

    Spiral out. Keep going...
    """
    pass

所有函数、方法和类都要包含docstring。对象数据模型方法(例如 __repr__ )通常是该规则的例外。

感谢你帮助世界变得更好!

文件贡献

欢迎对文档进行改进!文档文件位于 docs/ 代码库的目录。它们是用文字写的 reStructuredText 及使用 Sphinx 以生成完整的文档套件。

在提交文档时,请尽量遵循文档文件的样式。这意味着文本文件中的软限制为79个字符宽,并且是一种半正式、友好、平易近人的散文风格。

在呈现python代码时,使用单引号字符串( 'hello' 而不是 "hello"

错误报告

错误报告非常重要!但是,在你举起一个之前,请检查一下 GitHub issues , 打开和关闭, 确认以前没有报告过错误。重复的错误报告会消耗其他贡献者的时间,应该尽可能避免。

功能请求

请求处于永久性功能冻结状态,只有BDFL可以添加或批准新功能。维护人员认为,请求现在是一个功能完整的软件。

在维护一个广泛使用的开源项目时,最重要的技能之一是学习对建议的更改说“不”的能力,同时保持一个开放的耳朵和思想。

如果您认为功能缺失,请随时提出功能请求,但请务必注意,您的功能请求很可能不会被接受。