contributing.rst 2.9 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283
  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/shazow/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/shazow/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. #. Send a pull request and bug the maintainer until it gets merged and published.
  14. :) Make sure to add yourself to ``CONTRIBUTORS.txt``.
  15. Running the tests
  16. -----------------
  17. We use some external dependencies, multiple interpreters and code coverage
  18. analysis while running test suite. Our ``Makefile`` handles much of this for
  19. you as long as you're running it `inside of a virtualenv
  20. <http://docs.python-guide.org/en/latest/dev/virtualenvs/>`_::
  21. $ make test
  22. [... magically installs dependencies and runs tests on your virtualenv]
  23. Ran 182 tests in 1.633s
  24. OK (SKIP=6)
  25. Note that code coverage less than 100% is regarded as a failing run. Some
  26. platform-specific tests are skipped unless run in that platform. To make sure
  27. the code works in all of urllib3's supported platforms, you can run our ``tox``
  28. suite::
  29. $ make test-all
  30. [... tox creates a virtualenv for every platform and runs tests inside of each]
  31. py26: commands succeeded
  32. py27: commands succeeded
  33. py32: commands succeeded
  34. py33: commands succeeded
  35. py34: commands succeeded
  36. Our test suite `runs continuously on Travis CI
  37. <https://travis-ci.org/shazow/urllib3>`_ with every pull request.
  38. Sponsorship
  39. -----------
  40. Please consider sponsoring urllib3 development, especially if your company
  41. benefits from this library.
  42. We welcome your patronage on `Bountysource <https://www.bountysource.com/teams/urllib3>`_:
  43. * `Contribute a recurring amount to the team <https://salt.bountysource.com/checkout/amount?team=urllib3>`_
  44. * `Place a bounty on a specific feature <https://www.bountysource.com/teams/urllib3>`_
  45. Your contribution will go towards adding new features to urllib3 and making
  46. sure all functionality continues to meet our high quality standards.
  47. Project Grant
  48. -------------
  49. A grant for contiguous full-time development has the biggest impact for
  50. progress. Periods of 3 to 10 days allow a contributor to tackle substantial
  51. complex issues which are otherwise left to linger until somebody can't afford
  52. to not fix them.
  53. Contact `@shazow <https://github.com/shazow>`_ to arrange a grant for a core
  54. contributor.
  55. Huge thanks to all the companies and individuals who financially contributed to
  56. the development of urllib3. Please send a PR if you've donated and would like
  57. to be listed.
  58. * `Stripe <https://stripe.com/>`_ (June 23, 2014)
  59. .. * [Company] ([date])