贡献#
urllib3是一个社区维护的项目,我们很高兴接受贡献。
如果要添加新功能或修复错误:
Check for open issues 或者打开一个新的问题,围绕一个功能想法或一个bug展开讨论。有一个 贡献者友好 标记对于那些还不太熟悉代码库的人来说应该是理想的问题。
叉 urllib3 repository on Github 开始做你的改变。
编写一个测试,显示错误已修复或功能按预期工作。
使用命令将更改格式化为黑色 $ nox -rs format 并使用命令lint您的更改 nox -rs lint .
添加 changelog entry 。
发送一个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,以便在拉式请求描述中包括我们的版本清单。按照核对表做!