投稿人指南¶
如果你正在阅读这篇文章,你可能会对请求的贡献感兴趣。非常感谢你!开源项目的生存和消亡是基于他们从其他人那里得到的支持,而事实上,你甚至在考虑为请求项目做出贡献 very 你真大方。
本文件列出了对本项目作出贡献的指导方针和建议。如果你想做贡献,请先阅读本文档并了解如何为这个项目做出贡献。如果您有任何问题,请随时联系 Nate Prewitt , Ian Cordasco 或 Seth Michael Larson 主要维护人员。
本指南根据您考虑的贡献类型分为多个部分,其中一个部分涵盖了所有贡献者的一般指导原则。
亲切¶
热情点,或者在路上。. -肯尼斯·雷茨
请求有一个非常重要的规则来管理所有形式的贡献,包括报告错误或请求特性。这条黄金法则是” be cordial or be on your way “。
欢迎所有的贡献, 只要涉及到的每个人都受到尊重。
获得早期反馈¶
如果你在做贡献,不要觉得有必要坐在你的贡献上,直到它被完美地打磨和完善。这有助于所有相关人员尽早寻求反馈。提交一份早期的、未完成的稿件作为反馈,绝不会损害你接受稿件的机会,也可以避免你将大量工作投入到不适合项目的稿件中。
贡献适宜性¶
我们的项目维护人员对贡献是否适合请求有最后一句话。所有捐款将被仔细考虑,但有时,捐款将被拒绝,因为他们不符合当前的目标或项目的需要。
如果你的贡献被拒绝了,不要绝望!只要你遵守这些准则,你就有更好的机会让你的下一份贡献被接受。
代码贡献¶
提交代码的步骤¶
当贡献代码时,您需要遵循以下清单:
在Github上复刻存储库。
运行测试以确认它们都通过您的系统。如果他们不这样做,你就需要调查他们失败的原因。如果您自己无法诊断此问题,请按照本文档中的指南将其作为错误报告提出: 错误报告 .
编写测试来演示您的bug或特性。确保他们失败。
做你的改变。
再次运行整个测试套件,确认所有测试都通过 包括你刚加的那些.
向主存储库发送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可以添加或批准新功能。维护人员认为,请求现在是一个功能完整的软件。
在维护一个广泛使用的开源项目时,最重要的技能之一是学习对建议的更改说“不”的能力,同时保持一个开放的耳朵和思想。
如果您认为功能缺失,请随时提出功能请求,但请务必注意,您的功能请求很可能不会被接受。