贡献#

urllib3是一个社区维护的项目，我们很高兴接受贡献。

如果要添加新功能或修复错误：

  1. Check for open issues 或者打开一个新的问题，围绕一个功能想法或一个bug展开讨论。有一个 贡献者友好 标记对于那些还不太熟悉代码库的人来说应该是理想的问题。

  2. 叉 urllib3 repository on Github 开始做你的改变。

  3. 编写一个测试，显示错误已修复或功能按预期工作。

  4. 使用命令将更改格式化为黑色 $ nox -rs format 并使用命令lint您的更改 nox -rs lint .

  5. 添加 changelog entry 。

  6. 发送一个Pull请求并对维护程序进行错误检查，直到它被合并和发布。

设置开发环境#

为了设置开发环境，您只需要 nox 安装在您的计算机中：

$ python -m pip install --user --upgrade nox

运行测试#

在运行测试套件时，我们使用一些外部依赖项、多个解释器和代码覆盖率分析。我们的 noxfile.py 帮你处理很多事情：

$ nox --reuse-existing-virtualenvs --sessions test-3.7 test-3.9
[ Nox will create virtualenv if needed, install the specified dependencies, and run the commands in order.]
nox > Running session test-3.7
.......
.......
nox > Session test-3.7 was successful.
.......
.......
nox > Running session test-3.9
.......
.......
nox > Session test-3.9 was successful.

还有一个nox命令用于运行我们的所有测试和多个python版本：

$ nox --reuse-existing-virtualenvs --sessions test

请注意，代码覆盖率低于100%被视为失败运行。一些特定于平台的测试将被跳过，除非在该平台上运行。为了确保代码可以在所有支持URLlib3的S平台上运行，您可以运行我们的 nox 套房：：

$ nox --reuse-existing-virtualenvs --sessions test
[ Nox will create virtualenv if needed, install the specified dependencies, and run the commands in order.]
.......
.......
nox > Session test-3.7 was successful.
nox > Session test-3.8 was successful.
nox > Session test-3.9 was successful.
nox > Session test-3.10 was successful.
nox > Session test-pypy was successful.

我们的测试套件 runs continuously on GitHub Actions 每一次拉取请求。

要运行特定的测试或在不重新创建env的情况下快速重新运行，请执行以下操作：

$ nox --reuse-existing-virtualenvs --sessions test-3.8 -- pyTestArgument1 pyTestArgument2 pyTestArgumentN
[ Nox will create virtualenv, install the specified dependencies, and run the commands in order.]
nox > Running session test-3.8
nox > Re-using existing virtual environment at .nox/test-3-8.
.......
.......
nox > Session test-3.8 was successful.

后 -- 指示器，则任何参数都将传递给pytest。要指定精确的测试用例，以下语法也可以使用： test/dir/module_name.py::TestClassName::test_method_name （例如： test/with_dummyserver/test_https.py::TestHTTPS::test_simple ). 以下参数是传递给pytest的另一个有效示例： -k test_methode_name . 这些在开发新的测试用例时非常有用，而且没有必要每次迭代都重新运行整个测试套件。还可以为本地测试进一步参数化pytest。

对于所有有效参数，请检查 the pytest documentation .

为你的贡献获得报酬#

Urllib3有一个 pool of money hosted on Open Collective 团队用它来支付贡献者的工作费用。 That could be you, too! 如果您完成了标记为 "💰 Bounty $X00" label 那么你就有资格因你的工作而获得报酬。

  • 确保您能够 receive funds from Open Collective for working on OSS 。考虑一下你的雇佣合同和税收，看看有没有可能的限制。

  • 如果一个问题已经被分配给了GitHub上的某个人，那么他们很可能已经在这个问题上取得了实质性的进展，并将获得赏金。如果你对赏金感兴趣，你应该寻找没有分配给任何人的问题。

  • Don't "claim" issues or ask whether someone is already working on an issue. 相反，要专注于研究和处理问题中的任务。一旦您在某个问题的任务上取得了相当大的进展，我们就可以将您的帐户分配给该问题，以确保其他人不会同时开始处理该问题。

  • 如果你被分配到一个问题上，但在一周多的时间里没有取得进展或得到更新，你将被取消分配到这个问题中，以便让其他人有机会解决这个问题。

  • 标签上会显示完成一个问题将支付的金额(100美元、200美元、300美元等)。

  • 如果您对如何在Open Collective上创建发票有疑问 try reading their FAQ 。

  • 如果您有一个未在问题跟踪器中列出的关于urllib3的建议，请在您的建议中打开一个问题，我们的团队将讨论我们是否会为您在建议中所做的工作付费。

  • 如果您有其他问题，请联系 urllib3 Discord channel 或者通过电子邮件。

  • 上面的列表并不是关于如何/何时分配资金的标准或规则的详尽列表。 The final say on whether money will be distributed is up to maintainers.

该程序是一个实验，因此如果您对该过程有正面或负面的反馈，您可以通过上述渠道之一与维护人员联系。

请注意，这个计划不是一个“漏洞赏金”计划，我们目前不会向错误或安全漏洞记者发放资金。

运行本地代理#

如果您正在开发的功能涉及代理，您可以依靠我们开发的脚本在本地运行代理。

在本地运行HTTP代理：

$ python -m dummyserver.proxy

在本地运行HTTPS代理：

$ python -m dummyserver.https_proxy

为文档提供帮助#

您可以使用以下命令在本地构建文档 nox ：

$ nox -rs docs

在编写文档时，您应该遵循以下准则：

  • 使用顶层 urllib3.request() 函数用于较小的代码示例。有关更多涉及的示例，请使用PoolManager等。

  • 对所有字符串使用双引号。(产出、声明等)

  • 除了方法和url之外，在任何地方都使用关键字参数。(即 http.request("GET", "https://example.com", headers={...}) )

  • 除非需要HTTP，否则请在URL中随处使用HTTPS。

  • 代码示例和命名变量的规则：

    • PoolManager 实例应命名为 http 。(即 http = urllib3.PoolManager(...) )

    • ProxyManager 实例应命名为 proxy 。

    • ConnectionPool 实例应命名为 pool 。

    • Connection 实例应命名为 conn 。

    • HTTPResponse 实例应命名为 resp 。

    • 仅限使用 example.com 或 httpbin.org 例如URL

  • 代码片段中的注释应该是有用的，如果正在执行的操作很明显(例如解析JSON、发出请求)，则可以跳过该部分的注释。

  • 注释应始终位于代码段的上方，而不是下方，但包含结果的注释位于下方的打印语句除外。

  • 导入应该是它们自己的部分，用一行空格与示例的其余部分隔开。

  • 如果可能的话，应该尽量减少进口。使用导入urllib3而不是来自urllib3导入X。

  • 对导入的排序类似于isort，首先是标准库，然后是第三方(如urllib3)。

  • 在isort的情况下，区段之间通常不需要空格。

  • 添加打印语句及其下方的注释，以显示可能已压缩的输出。

  • 这有助于用户使用复制-粘贴按钮立即查看脚本的结果。

发行版#

任何贡献者都可以创建发布候选版本。

  • 宣布打算在不和谐的情况下发布，看看是否有人想要在最后一刻做出改变。

  • 跑 towncrier build 要更新 CHANGES.rst 使用发行说明，根据需要进行调整。

  • 更新 urllib3/__init__.py 具有正确的版本号

  • 将更改提交到 release-X.Y.Z 布兰奇。

  • 创建拉式请求并追加 &expand=1&template=release.md 在提交之前将我们的版本清单添加到URL，以便在拉式请求描述中包括我们的版本清单。

  • 按照核对表做！