contributing.rst 8.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242
  1. #############################
  2. Contributing to pytest-django
  3. #############################
  4. Like every open-source project, pytest-django is always looking for motivated
  5. individuals to contribute to its source code. However, to ensure the highest
  6. code quality and keep the repository nice and tidy, everybody has to follow a
  7. few rules (nothing major, I promise :) )
  8. *********
  9. Community
  10. *********
  11. The fastest way to get feedback on contributions/bugs is usually to open an
  12. issue in the `issue tracker`_.
  13. Discussions also happen via IRC in #pylib on irc.freenode.org. You may also
  14. be interested in following `@andreaspelme`_ on Twitter.
  15. *************
  16. In a nutshell
  17. *************
  18. Here's what the contribution process looks like, in a bullet-points fashion:
  19. #. pytest-django is hosted on `GitHub`_, at
  20. https://github.com/pytest-dev/pytest-django
  21. #. The best method to contribute back is to create an account there and fork
  22. the project. You can use this fork as if it was your own project, and should
  23. push your changes to it.
  24. #. When you feel your code is good enough for inclusion, "send us a `pull
  25. request`_", by using the nice GitHub web interface.
  26. *****************
  27. Contributing Code
  28. *****************
  29. Getting the source code
  30. =======================
  31. - Code will be reviewed and tested by at least one core developer, preferably
  32. by several. Other community members are welcome to give feedback.
  33. - Code *must* be tested. Your pull request should include unit-tests (that
  34. cover the piece of code you're submitting, obviously).
  35. - Documentation should reflect your changes if relevant. There is nothing worse
  36. than invalid documentation.
  37. - Usually, if unit tests are written, pass, and your change is relevant, then
  38. your pull request will be merged.
  39. Since we're hosted on GitHub, pytest-django uses `git`_ as a version control
  40. system.
  41. The `GitHub help`_ is very well written and will get you started on using git
  42. and GitHub in a jiffy. It is an invaluable resource for newbies and oldtimers
  43. alike.
  44. Syntax and conventions
  45. ======================
  46. We try to conform to `PEP8`_ as much as possible. A few highlights:
  47. - Indentation should be exactly 4 spaces. Not 2, not 6, not 8. **4**. Also,
  48. tabs are evil.
  49. - We try (loosely) to keep the line length at 79 characters. Generally the rule
  50. is "it should look good in a terminal-based editor" (eg vim), but we try not
  51. be [Godwin's law] about it.
  52. Process
  53. =======
  54. This is how you fix a bug or add a feature:
  55. #. `fork`_ the repository on GitHub.
  56. #. Checkout your fork.
  57. #. Hack hack hack, test test test, commit commit commit, test again.
  58. #. Push to your fork.
  59. #. Open a pull request.
  60. Tests
  61. =====
  62. Having a wide and comprehensive library of unit-tests and integration tests is
  63. of exceeding importance. Contributing tests is widely regarded as a very
  64. prestigious contribution (you're making everybody's future work much easier by
  65. doing so). Good karma for you. Cookie points. Maybe even a beer if we meet in
  66. person :)
  67. Generally tests should be:
  68. - Unitary (as much as possible). I.E. should test as much as possible only on
  69. one function/method/class. That's the very definition of unit tests.
  70. Integration tests are also interesting obviously, but require more time to
  71. maintain since they have a higher probability of breaking.
  72. - Short running. No hard numbers here, but if your one test doubles the time it
  73. takes for everybody to run them, it's probably an indication that you're
  74. doing it wrong.
  75. In a similar way to code, pull requests will be reviewed before pulling
  76. (obviously), and we encourage discussion via code review (everybody learns
  77. something this way) or in the IRC channel.
  78. Running the tests
  79. -----------------
  80. There is a Makefile in the repository which aids in setting up a virtualenv
  81. and running the tests::
  82. $ make test
  83. You can manually create the virtualenv using::
  84. $ make testenv
  85. This will install a virtualenv with pytest and the latest stable version of
  86. Django. The virtualenv can then be activated with::
  87. $ source bin/activate
  88. Then, simply invoke pytest to run the test suite::
  89. $ pytest --ds=pytest_django_test.settings_sqlite
  90. tox can be used to run the test suite under different configurations by
  91. invoking::
  92. $ tox
  93. There is a huge number of unique test configurations (98 at the time of
  94. writing), running them all will take a long time. All valid configurations can
  95. be found in `tox.ini`. To test against a few of them, invoke tox with the `-e`
  96. flag::
  97. $ tox -e py36-dj111-postgres,py27-dj111-mysql_innodb
  98. This will run the tests on Python 3.6/Django 1.11/PostgeSQL and Python
  99. 2.7/Django 1.11/MySQL.
  100. Measuring test coverage
  101. -----------------------
  102. Some of the tests are executed in subprocesses. Because of that regular
  103. coverage measurements (using pytest-cov plugin) are not reliable.
  104. If you want to measure coverage you'll need to create .pth file as described in
  105. `subprocess section of coverage documentation`_. If you're using
  106. ``setup.py develop`` you should uninstall pytest_django (using pip)
  107. for the time of measuring coverage.
  108. You'll also need mysql and postgres databases. There are predefined settings
  109. for each database in the tests directory. You may want to modify these files
  110. but please don't include them in your pull requests.
  111. After this short initial setup you're ready to run tests::
  112. $ COVERAGE_PROCESS_START=`pwd`/.coveragerc COVERAGE_FILE=`pwd`/.coverage PYTHONPATH=`pwd` pytest --ds=pytest_django_test.settings_postgres
  113. You should repeat the above step for sqlite and mysql before the next step.
  114. This step will create a lot of ``.coverage`` files with additional suffixes for
  115. every process.
  116. The final step is to combine all the files created by different processes and
  117. generate the html coverage report::
  118. $ coverage combine
  119. $ coverage html
  120. Your coverage report is now ready in the ``htmlcov`` directory.
  121. Continuous integration
  122. ----------------------
  123. `Travis`_ is used to automatically run all tests against all supported versions
  124. of Python, Django and different database backends.
  125. The `pytest-django Travis`_ page shows the latest test run. Travis will
  126. automatically pick up pull requests, test them and report the result directly
  127. in the pull request.
  128. **************************
  129. Contributing Documentation
  130. **************************
  131. Perhaps considered "boring" by hard-core coders, documentation is sometimes
  132. even more important than code! This is what brings fresh blood to a project,
  133. and serves as a reference for oldtimers. On top of this, documentation is the
  134. one area where less technical people can help most - you just need to write a
  135. semi-decent English. People need to understand you. We don't care about style
  136. or correctness.
  137. Documentation should be:
  138. - We use `Sphinx`_/`restructuredText`_. So obviously this is the format you
  139. should use :) File extensions should be .rst.
  140. - Written in English. We can discuss how it would bring more people to the
  141. project to have a Klingon translation or anything, but that's a problem we
  142. will ask ourselves when we already have a good documentation in English.
  143. - Accessible. You should assume the reader to be moderately familiar with
  144. Python and Django, but not anything else. Link to documentation of libraries
  145. you use, for example, even if they are "obvious" to you (South is the first
  146. example that comes to mind - it's obvious to any Django programmer, but not
  147. to any newbie at all).
  148. A brief description of what it does is also welcome.
  149. Pulling of documentation is pretty fast and painless. Usually somebody goes
  150. over your text and merges it, since there are no "breaks" and that GitHub
  151. parses rst files automagically it's really convenient to work with.
  152. Also, contributing to the documentation will earn you great respect from the
  153. core developers. You get good karma just like a test contributor, but you get
  154. double cookie points. Seriously. You rock.
  155. .. note::
  156. This very document is based on the contributing docs of the `django CMS`_
  157. project. Many thanks for allowing us to steal it!
  158. .. _fork: https://github.com/pytest-dev/pytest-django
  159. .. _issue tracker: https://github.com/pytest-dev/pytest-django/issues
  160. .. _Sphinx: http://sphinx.pocoo.org/
  161. .. _PEP8: http://www.python.org/dev/peps/pep-0008/
  162. .. _GitHub : http://www.github.com
  163. .. _GitHub help : http://help.github.com
  164. .. _freenode : http://freenode.net/
  165. .. _@andreaspelme : https://twitter.com/andreaspelme
  166. .. _pull request : http://help.github.com/send-pull-requests/
  167. .. _git : http://git-scm.com/
  168. .. _restructuredText: http://docutils.sourceforge.net/docs/ref/rst/introduction.html
  169. .. _django CMS: https://www.django-cms.org/
  170. .. _Travis: https://travis-ci.org/
  171. .. _pytest-django Travis: https://travis-ci.org/pytest-dev/pytest-django
  172. .. _`subprocess section of coverage documentation`: http://nedbatchelder.com/code/coverage/subprocess.html