contributing.rst 8.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177
  1. Contributing
  2. ============
  3. urllib3 is a community-maintained project and we happily accept contributions.
  4. If you wish to add a new feature or fix a bug:
  5. #. `Check for open issues <https://github.com/urllib3/urllib3/issues>`_ or open
  6. a fresh issue to start a discussion around a feature idea or a bug. There is
  7. a *Contributor Friendly* tag for issues that should be ideal for people who
  8. are not very familiar with the codebase yet.
  9. #. Fork the `urllib3 repository on Github <https://github.com/urllib3/urllib3>`_
  10. to start making your changes.
  11. #. Write a test which shows that the bug was fixed or that the feature works
  12. as expected.
  13. #. Format your changes with black using command `$ nox -rs format` and lint your
  14. changes using command `nox -rs lint`.
  15. #. Send a pull request and bug the maintainer until it gets merged and published.
  16. Setting up your development environment
  17. ---------------------------------------
  18. In order to setup the development environment all that you need is
  19. `nox <https://nox.thea.codes/en/stable/index.html>`_ installed in your machine::
  20. $ python -m pip install --user --upgrade nox
  21. Running the tests
  22. -----------------
  23. We use some external dependencies, multiple interpreters and code coverage
  24. analysis while running test suite. Our ``noxfile.py`` handles much of this for
  25. you::
  26. $ nox --reuse-existing-virtualenvs --sessions test-2.7 test-3.7
  27. [ Nox will create virtualenv if needed, install the specified dependencies, and run the commands in order.]
  28. nox > Running session test-2.7
  29. .......
  30. .......
  31. nox > Session test-2.7 was successful.
  32. .......
  33. .......
  34. nox > Running session test-3.7
  35. .......
  36. .......
  37. nox > Session test-3.7 was successful.
  38. There is also a nox command for running all of our tests and multiple python
  39. versions.::
  40. $ nox --reuse-existing-virtualenvs --sessions test
  41. Note that code coverage less than 100% is regarded as a failing run. Some
  42. platform-specific tests are skipped unless run in that platform. To make sure
  43. the code works in all of urllib3's supported platforms, you can run our ``nox``
  44. suite::
  45. $ nox --reuse-existing-virtualenvs --sessions test
  46. [ Nox will create virtualenv if needed, install the specified dependencies, and run the commands in order.]
  47. .......
  48. .......
  49. nox > Session test-2.7 was successful.
  50. nox > Session test-3.6 was successful.
  51. nox > Session test-3.7 was successful.
  52. nox > Session test-3.8 was successful.
  53. nox > Session test-3.9 was successful.
  54. nox > Session test-3.10 was successful.
  55. nox > Session test-3.11 was successful.
  56. nox > Session test-pypy was successful.
  57. Our test suite `runs continuously on GitHub Actions
  58. <https://github.com/urllib3/urllib3/actions>`_ with every pull request.
  59. To run specific tests or quickly re-run without nox recreating the env, do the following::
  60. $ nox --reuse-existing-virtualenvs --sessions test-3.8 -- pyTestArgument1 pyTestArgument2 pyTestArgumentN
  61. [ Nox will create virtualenv, install the specified dependencies, and run the commands in order.]
  62. nox > Running session test-3.8
  63. nox > Re-using existing virtual environment at .nox/test-3-8.
  64. .......
  65. .......
  66. nox > Session test-3.8 was successful.
  67. After the ``--`` indicator, any arguments will be passed to pytest.
  68. To specify an exact test case the following syntax also works:
  69. ``test/dir/module_name.py::TestClassName::test_method_name``
  70. (eg.: ``test/with_dummyserver/test_https.py::TestHTTPS::test_simple``).
  71. The following argument is another valid example to pass to pytest: ``-k test_methode_name``.
  72. These are useful when developing new test cases and there is no point
  73. re-running the entire test suite every iteration. It is also possible to
  74. further parameterize pytest for local testing.
  75. For all valid arguments, check `the pytest documentation
  76. <https://docs.pytest.org/en/stable/usage.html#stopping-after-the-first-or-n-failures>`_.
  77. Getting paid for your contributions
  78. -----------------------------------
  79. urllib3 has a `pool of money hosted on Open Collective <https://opencollective.com/urllib3#category-BUDGET>`_
  80. which the team uses to pay contributors for their work. **That could be you, too!** If you complete all tasks in an issue
  81. that is marked with the `"💰 Bounty $X00" label <https://github.com/urllib3/urllib3/issues?q=is%3Aopen+is%3Aissue+label%3A%22%F0%9F%92%B0+Bounty+%24100%22%2C%22%F0%9F%92%B0+Bounty+%24200%22%2C%22%F0%9F%92%B0+Bounty+%24300%22%2C%22%F0%9F%92%B0+Bounty+%24400%22%2C%22%F0%9F%92%B0+Bounty+%24500%22+no%3Aassignee>`_ then you're eligible to be paid for your work.
  82. - Ensure that you're able to `receive funds from Open Collective for working on OSS <https://docs.opencollective.com/help/expenses-and-getting-paid/submitting-expenses>`_.
  83. Consider your employment contract and taxes for possible restrictions.
  84. - If an issue is already assigned to someone on GitHub then it's likely they've
  85. made substantial progress on the issue and will be given the bounty.
  86. If you're interested in bounties you should look for issues which
  87. aren't assigned to anyone.
  88. - **Don't "claim" issues or ask whether someone is already working on an issue.**
  89. Instead, focus on researching and working on the tasks in the issue. Once you
  90. have made considerable progress on the tasks in an issue we can assign your
  91. account to the issue to ensure others don't start working on it in parallel.
  92. - If you've been assigned to an issue and haven't made progress or given an update
  93. in over a week you will be unassigned from the issue to allow others a chance
  94. at solving the issue.
  95. - The amount you will be paid for the completing an issue is shown in the label (either $100, $200, $300, etc).
  96. - If you have questions about how to create an invoice on Open Collective
  97. `try reading their FAQ <https://docs.opencollective.com/help/expenses-and-getting-paid/expenses>`_.
  98. - If you have a proposal to work on urllib3 that's not listed in the issue tracker please open an issue
  99. with your proposal and our team will discuss whether we'd pay for your work on your proposal.
  100. - If you have other questions get in contact with a maintainer in the `urllib3 Discord channel <https://discord.gg/urllib3>`_ or via email.
  101. - The list above isn't an exhaustive list of criteria or rules for how/when money is distributed.
  102. **The final say on whether money will be distributed is up to maintainers.**
  103. This program is an experiment so if you have positive or negative feedback on the process you can contact the maintainers through one of the above channels.
  104. Note that this program isn't a "bug bounty" program, we don't distribute funds to reporters of bugs or security vulnerabilities at this time.
  105. Contributing to documentation
  106. -----------------------------
  107. You can build the docs locally using ``nox``:
  108. .. code-block:: bash
  109. $ nox -rs docs
  110. While writing documentation you should follow these guidelines:
  111. - Use the top-level ``urllib3.request()`` function for smaller code examples. For more involved examples use PoolManager, etc.
  112. - Use double quotes for all strings. (Output, Declaration etc.)
  113. - Use keyword arguments everywhere except for method and url. (ie ``http.request("GET", "https://example.com", headers={...})`` )
  114. - Use HTTPS in URLs everywhere unless HTTP is needed.
  115. - Rules for code examples and naming variables:
  116. - ``PoolManager`` instances should be named ``http``. (ie ``http = urllib3.PoolManager(...)``)
  117. - ``ProxyManager`` instances should be named ``proxy``.
  118. - ``ConnectionPool`` instances should be named ``pool``.
  119. - ``Connection`` instances should be named ``conn``.
  120. - ``HTTPResponse`` instances should be named ``resp``.
  121. - Only use ``example.com`` or ``httpbin.org`` for example URLs
  122. - Comments within snippets should be useful, if what's being done is apparent
  123. (such as parsing JSON, making a request) then it can be skipped for that section.
  124. - Comments should always go above a code section rather than below with the exception of print
  125. statements where the comment containing the result goes below.
  126. - Imports should be their own section separated from the rest of the example with a line of whitespace.
  127. - Imports should minimized if possible. Use import urllib3 instead of from urllib3 import X.
  128. - Sort imports similarly to isort, standard library first and third-party (like urllib3) come after.
  129. - No whitespace is required between the sections as normally would be in case of isort.
  130. - Add print statements along with a comment below them showing the output, potentially compressed.
  131. - This helps users using the copy-paste button immediately see the results from a script.
  132. Releases
  133. --------
  134. A release candidate can be created by any contributor.
  135. - Announce intent to release on Discord, see if anyone wants to include last minute
  136. changes.
  137. - Update ``urllib3/_version.py`` with the proper version number
  138. - Commit the changes to a ``release-X.Y.Z`` branch.
  139. - Create a pull request and append ``&expand=1&template=release.md`` to the URL before
  140. submitting in order to include our release checklist in the pull request description.
  141. - Follow the checklist!