贡献者指南

如果您正在阅读本文，您可能对为 Requests 做出贡献感兴趣。非常感谢！开源项目的生死存亡取决于他们从其他人那里得到的支持，事实上，您甚至考虑为 Requests 项目做出贡献非常慷慨。

本文档列出了为该项目做出贡献的指导方针和建议。如果您正在考虑做出贡献，请首先阅读本文档并了解如何为该项目做出贡献。如果您有任何问题，请随时联系主要维护者 Nate Prewitt、Ian Cordasco 或 Seth Michael Larson。

该指南根据您想做出的贡献类型分为几个部分，其中一个部分涵盖了所有贡献者的一般准则。

亲切

亲切或随你。 —肯尼斯·赖茨

Requests 有一个非常重要的规则来管理所有形式的贡献，包括报告错误或请求功能。这条黄金法则是“ 亲切或随心所欲”。

欢迎所有贡献，只要所有参与的人都受到尊重。

获得早期反馈

如果你正在贡献，不要觉得有必要坐在你的贡献上，直到它被完美地打磨和完成。它可以帮助您参与的每个人尽早寻求反馈。提交早期的、未完成的贡献版本以供反馈绝不会影响您获得该贡献被接受的机会，并且可以避免您将大量工作投入到不适合该项目的贡献中。

供款适用性

我们的项目维护人员对贡献是否适合请求拥有最终决定权。所有的贡献都会被仔细考虑，但有时，贡献会被拒绝，因为它们不适合项目的当前目标或需求。

如果您的贡献被拒绝，请不要绝望！只要您遵循这些准则，您将有更好的机会让您的下一个贡献被接受。

代码贡献

提交代码的步骤

贡献代码时，您需要遵循以下清单：

在 GitHub 上分叉存储库。
运行测试以确认它们都通过了您的系统。如果他们不这样做，您将需要调查他们失败的原因。如果您无法自行诊断，请按照本文档中的指南将其作为错误报告提出：错误报告。
编写测试来演示您的错误或功能。确保他们失败。
做出改变。
再次运行整个测试套件，确认所有测试都通过了 ，包括您刚刚添加的测试 。
向主存储库的 master 分支发送 GitHub 拉取请求。 GitHub Pull Requests 是该项目中预期的代码协作方法。

以下小节更详细地介绍了上述一些要点。

代码审查

贡献在经过代码审查之前不会被合并。除非您强烈反对，否则您应该实施任何代码审查反馈。如果您反对代码审查反馈，您应该清楚而冷静地说明您的情况。如果在这样做之后，判断反馈仍然适用，您必须应用反馈或撤回您的贡献。

新贡献者

如果您是开源新手或相对较新的人，欢迎您！ Requests 旨在成为对开源世界的温和介绍。如果您担心如何最好地做出贡献，请考虑向维护者（如上所列）发送邮件并寻求帮助。

另请查看获取早期反馈部分。

Kenneth Reitz 的 Code Style™

请求代码库使用 PEP 8 代码样式。

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

行长可以超过 79 个字符，方便时可以超过 100 个字符。
行长度可以超过 100 个字符，否则会 非常不方便 。
始终使用单引号字符串（例如 '#flatearth')，除非字符串中出现单引号。

此外，PEP8 为行延续推荐的样式之一完全缺乏品味，并且不允许在请求代码库中使用：

# 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,
)

文档字符串遵循以下语法：

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

所有函数、方法和类都将包含文档字符串。对象数据模型方法（例如 __repr__) 通常是此规则的例外。

感谢您帮助让世界变得更美好！

文档贡献

文档改进总是受欢迎的！文档文件位于代码库的 docs/ 目录中。它们用 reStructuredText 编写，并使用 Sphinx 生成全套文档。

在贡献文档时，请尽量遵循文档文件的风格。这意味着您的文本文件中的软限制为 79 个字符宽，并且采用半正式但友好且平易近人的散文风格。

呈现 Python 代码时，使用单引号字符串（'hello' 而不是 "hello"）。

错误报告

错误报告非常重要！不过，在提出问题之前，请检查 GitHub 问题、 已打开和已关闭 ，以确认之前未报告过该错误。重复的错误报告会大量消耗其他贡献者的时间，应尽可能避免。

功能请求

请求处于永久功能冻结状态，只有 BDFL 可以添加或批准新功能。维护者认为 Requests 目前是一个功能完整的软件。

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

如果您认为缺少某个功能，请随时提出功能请求，但请注意，您的功能请求很有可能不会被接受。

贡献者指南 — 请求文档