1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
|
Contributing
============
urllib3 is a community-maintained project and we happily accept contributions.
If you wish to add a new feature or fix a bug:
#. `Check for open issues <https://github.com/urllib3/urllib3/issues>`_ or open
a fresh issue to start a discussion around a feature idea or a bug. There is
a *Contributor Friendly* tag for issues that should be ideal for people who
are not very familiar with the codebase yet.
#. Fork the `urllib3 repository on Github <https://github.com/urllib3/urllib3>`_
to start making your changes.
#. Write a test which shows that the bug was fixed or that the feature works
as expected.
#. Format your changes with black using command `$ nox -rs format` and lint your
changes using command `nox -rs lint`.
#. Send a pull request and bug the maintainer until it gets merged and published.
:) Make sure to add yourself to ``CONTRIBUTORS.txt``.
Setting up your development environment
---------------------------------------
In order to setup the development environment all that you need is
`nox <https://nox.thea.codes/en/stable/index.html>`_ installed in your machine::
$ pip install --user --upgrade nox
Running the tests
-----------------
We use some external dependencies, multiple interpreters and code coverage
analysis while running test suite. Our ``noxfile.py`` handles much of this for
you::
$ nox --reuse-existing-virtualenvs --sessions test-2.7 test-3.7
[ Nox will create virtualenv if needed, install the specified dependencies, and run the commands in order.]
nox > Running session test-2.7
.......
.......
nox > Session test-2.7 was successful.
.......
.......
nox > Running session test-3.7
.......
.......
nox > Session test-3.7 was successful.
There is also a nox command for running all of our tests and multiple python
versions.::
$ nox --reuse-existing-virtualenvs --sessions test
Note that code coverage less than 100% is regarded as a failing run. Some
platform-specific tests are skipped unless run in that platform. To make sure
the code works in all of urllib3's supported platforms, you can run our ``tox``
suite::
$ 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-2.7 was successful.
nox > Session test-3.4 was successful.
nox > Session test-3.5 was successful.
nox > Session test-3.6 was successful.
nox > Session test-3.7 was successful.
nox > Session test-3.8 was successful.
nox > Session test-pypy was successful.
Our test suite `runs continuously on Travis CI
<https://travis-ci.org/urllib3/urllib3>`_ with every pull request.
To run specific tests or quickly re-run without nox recreating the env, do the following::
$ 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.
After the ``--`` indicator, any arguments will be passed to pytest.
To specify an exact test case the following syntax also works:
``test/dir/module_name.py::TestClassName::test_method_name``
(eg.: ``test/with_dummyserver/test_https.py::TestHTTPS::test_simple``).
The following argument is another valid example to pass to pytest: ``-k test_methode_name``.
These are useful when developing new test cases and there is no point
re-running the entire test suite every iteration. It is also possible to
further parameterize pytest for local testing.
For all valid arguments, check `the pytest documentation
<https://docs.pytest.org/en/stable/usage.html#stopping-after-the-first-or-n-failures>`_.
Releases
--------
A release candidate can be created by any contributor by creating a branch
named ``release-x.x`` where ``x.x`` is the version of the proposed release.
- Update ``CHANGES.rst`` and ``urllib3/__init__.py`` with the proper version number
and commit the changes to ``release-x.x``.
- Open a pull request to merge the ``release-x.x`` branch into the ``master`` branch.
- Integration tests are run against the release candidate on Travis. From here on all
the steps below will be handled by a maintainer so unless you receive review comments
you are done here.
- Once the pull request is squash merged into master the merging maintainer
will tag the merge commit with the version number:
- ``git tag -a 1.24.1 [commit sha]``
- ``git push origin master --tags``
- After the commit is tagged Travis will build the tagged commit and upload the sdist and wheel
to PyPI and create a draft release on GitHub for the tag. The merging maintainer will
ensure that the PyPI sdist and wheel are properly uploaded.
- The merging maintainer will mark the draft release on GitHub as an approved release.
|
