contributor-guide.rst 7.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243
  1. .. _contributor-guide:
  2. Contributor Guide
  3. =================
  4. This document is for developers who want to contribute code to this project.
  5. Any contributions are welcome and greatly appreciated!
  6. This project follows the common conventions of a Python/GitHub project. So if
  7. you're already an experienced Python/GitHub user, it should be straightforward
  8. for you to set up your development environment and send patches. Generally, the
  9. steps include:
  10. 1. Fork and clone the repo
  11. 2. Create a virtualenv for this project
  12. 3. Install dependent packages with ``pip install -e .``
  13. 4. Install test dependent packages with ``pip install -r requirements-test.txt``
  14. 5. Make your changes to the code
  15. 6. Run tests with ``pytest`` and ``tox``
  16. 7. Commit and push your changes
  17. 8. Send a pull request
  18. 9. Wait to be reviewed and get merged!
  19. If you're not familiar with any of the above steps, read the following
  20. instructions.
  21. Forking
  22. -------
  23. Fork_ is like copying someone else's project to your account, so you can start
  24. your own independent development without interfering with the original one.
  25. To fork HTTP Prompt, just click the **Fork** button on HTTP Prompt's GitHub
  26. project page. Then you clone your fork to your local computer::
  27. $ cd ~/Projects
  28. $ git clone git@github.com:{YOUR_USERNAME}/http-prompt.git
  29. Read `Forking Projects`_ on GitHub to learn more.
  30. Working with virtualenv
  31. -----------------------
  32. *virtualenv* is the de facto standard tool when developing a Python project.
  33. Instead of polluting your system-wide Python installation with different Python
  34. projects, virtualenv creates an isolated Python environment exclusively for a
  35. Python project.
  36. There are several tools you can use for managing virtualenvs. In this guide,
  37. we'll show you how to use pyenv_ and pyenv-virtualenv_, which is one of the
  38. most popular virtualenv management tools.
  39. Make sure you have installed pyenv_ and pyenv-virtualenv_ first.
  40. HTTP Prompt should work on Python 2.6, 2.7, 3.3 to 3.6. You can use any
  41. of these Python versions as your development environment, but using the latest
  42. version (3.6.x) is probably the best. You can install the latest Python with
  43. pyenv::
  44. $ pyenv install 3.6.0
  45. This will install Python 3.6.0 in ``~/.pyenv/versions/3.6.0`` directory. To
  46. create a virtualenv for HTTP Prompt, do::
  47. $ pyenv virtualenv 3.6.0 http-prompt
  48. The command means: create a virtualenv named "http-prompt" based on Python
  49. 3.6.0. The virtualenv can be found at ``~/.pyenv/versions/3.6.0/envs/http-prompt``.
  50. To activate the virtualenv, do::
  51. $ pyenv activate http-prompt
  52. This will switch your Python environment from the system-wide Python to the
  53. virtualenv's (named "http-prompt") Python.
  54. To go back to the system-wide Python, you have to deactivate the virtualenv::
  55. $ pyenv deactivate
  56. Refer to pyenv_ and pyenv-virtualenv_ if anything else is unclear.
  57. Installing Dependent Packages
  58. -----------------------------
  59. The dependent packages should be installed on a virtualenv, so make sure you
  60. activate your virtualenv first. If not, do::
  61. $ pyenv activate http-prompt
  62. It is also recommended to use the latest version of pip. You can upgrade it
  63. with::
  64. $ pip install -U pip
  65. Install HTTP Prompt with its dependent packages::
  66. $ cd ~/Projects/http-prompt
  67. $ pip install -e .
  68. ``pip install -e .`` means install the ``http-prompt`` package in editable mode
  69. (or developer mode). This allows you to edit code directly in
  70. ``~/Projects/http-prompt`` without reinstalling the package. Without the ``-e``
  71. option, the package will be installed to Python's ``site-packages`` directory,
  72. which is not convenient for developing.
  73. Installing Test Dependent Packages
  74. ----------------------------------
  75. Test requirements are placed in a separate file named ``requirements-test.txt``.
  76. To install them, do::
  77. $ cd ~/Projects/http-prompt
  78. $ pip install -r requirements-test.txt
  79. Making Your Changes
  80. -------------------
  81. Code Style
  82. ~~~~~~~~~~
  83. Always lint your code with Flake8_. You can set it up in your code editor or
  84. simply use ``flake8`` in the command line.
  85. `The Hitchhiker’s Guide to Python`_ provides the best Python coding practices.
  86. We recommend anyone who wants to write good Python code to read it.
  87. Adding Features
  88. ~~~~~~~~~~~~~~~
  89. Before you add a new feature, make sure you create an issue making a proposal
  90. first, because you don't want to waste your time on something that the
  91. community don't agree upon.
  92. Python 2 and 3 Compatibility
  93. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  94. HTTP Prompt is compatible with Python 2 and 3. Keep in mind that you're coding
  95. for Python 2 and 3 at the same time. You can use Tox_ (see below) to make sure
  96. the code is runnable on both Python 2 and 3.
  97. Documentation
  98. ~~~~~~~~~~~~~
  99. Documentation is written in Sphinx_. To build documentation, you need to
  100. install Sphinx_ first::
  101. $ pip install sphinx
  102. To build and view documentation in HTML, do::
  103. $ cd ~/Projects/http-prompt/docs
  104. $ make html
  105. $ open _build/html/index.html
  106. Running Tests
  107. -------------
  108. Single Python Version
  109. ~~~~~~~~~~~~~~~~~~~~~
  110. Make sure your virtualenv is activated. To run tests, do::
  111. $ cd ~/Projects/http-prompt
  112. $ pytest
  113. ``pytest`` runs the tests with your virtualenv's Python version. This is good
  114. for fast testing. To test the code against multiple Python versions, you use
  115. Tox_.
  116. Multiple Python Versions
  117. ~~~~~~~~~~~~~~~~~~~~~~~~
  118. All the commands in this section should **NOT** be run in a virtualenv.
  119. Deactivate it first if you're in a virtualenv::
  120. $ pyenv deactivate
  121. Make sure you have installed all the Python versions we're targeting. If not,
  122. do::
  123. $ pyenv install 3.6.0
  124. $ pyenv install 3.7.0
  125. $ pyenv install 3.8.0
  126. To use Tox_ with pyenv_, you have to instruct pyenv to use multiple Python
  127. versions for the project::
  128. $ cd ~/Projects/http-prompt
  129. $ pyenv local 3.6.0 3.7.0 3.8.0
  130. This will generate a ``.python-version`` in the project directory::
  131. $ cat ~/Projects/http-prompt/.python-version
  132. 3.6.0
  133. 3.7.0
  134. 3.8.0
  135. This tells pyenv_ to choose a Python version based on the above order. In this
  136. case, 3.6.0 is the first choice, so any Python executables (such as ``python``
  137. and ``pip``) will be automatically mapped to the ones in
  138. ``~/.pyenv/versions/3.8.0/bin``.
  139. We want to run ``tox`` using on Python 3.8.0. Make sure you have installed
  140. Tox_::
  141. $ pip install tox
  142. To run tests, execute ``tox``::
  143. $ cd ~/Projects/http-prompt
  144. $ tox
  145. Tox_ will install the test Python environments in the ``.tox/`` directory in
  146. the project directory, and run the test code against all the Python versions
  147. listed above.
  148. Code Review
  149. -----------
  150. Once you made changes and all the tests pass, push your modified code to your
  151. GitHub account. Submit a pull request (PR) on GitHub for the maintainers to
  152. review. If the patch is good, The maintainers will merge it to the master
  153. branch and ship the new code in the next release. If the patch needs
  154. improvements, we'll give you feedback so you can modify accordingly and
  155. resubmit it to the PR.
  156. .. _Flake8: http://flake8.pycqa.org/en/latest/index.html
  157. .. _Fork: https://en.wikipedia.org/wiki/Fork_(software_development)
  158. .. _Forking Projects: https://guides.github.com/activities/forking/
  159. .. _pyenv-virtualenv: https://github.com/yyuu/pyenv-virtualenv
  160. .. _pyenv: https://github.com/yyuu/pyenv
  161. .. _Sphinx: http://www.sphinx-doc.org/
  162. .. _The Hitchhiker’s Guide to Python: http://docs.python-guide.org/en/latest/
  163. .. _Tox: https://tox.readthedocs.io/en/latest/