forked from extern/httpie-cli
184 lines
5.1 KiB
ReStructuredText
184 lines
5.1 KiB
ReStructuredText
######################
|
||
Contributing to HTTPie
|
||
######################
|
||
|
||
Bug reports and code and documentation patches are welcome. You can
|
||
help this project also by using the development version of HTTPie
|
||
and by reporting any bugs you might encounter.
|
||
|
||
1. Reporting bugs
|
||
=================
|
||
|
||
**It's important that you provide the full command argument list
|
||
as well as the output of the failing command.**
|
||
Use the ``--debug`` flag and copy&paste both the command and its output
|
||
to your bug report, e.g.:
|
||
|
||
.. code-block:: bash
|
||
|
||
$ http --debug [COMPLETE ARGUMENT LIST THAT TRIGGERS THE ERROR]
|
||
[COMPLETE OUTPUT]
|
||
|
||
|
||
2. Contributing Code and Docs
|
||
=============================
|
||
|
||
Before working on a new feature or a bug, please browse `existing issues`_
|
||
to see whether it has been previously discussed. If the change in question
|
||
is a bigger one, it's always good to discuss before you start working on
|
||
it.
|
||
|
||
|
||
Development Environment
|
||
--------------------------------
|
||
|
||
|
||
Getting the code
|
||
****************
|
||
|
||
Go to https://github.com/jakubroztocil/httpie and fork the project repository.
|
||
|
||
|
||
.. code-block:: bash
|
||
|
||
# Clone your fork
|
||
git clone git@github.com:<YOU>/httpie.git
|
||
|
||
# Enter the project directory
|
||
cd httpie
|
||
|
||
# Create a branch for your changes
|
||
git checkout -b my_topical_branch
|
||
|
||
|
||
Setup
|
||
*****
|
||
|
||
The `Makefile`_ contains a bunch of tasks to get you started. Just run
|
||
the following command, which:
|
||
|
||
|
||
* Creates an isolated Python virtual environment inside ``./venv``
|
||
(via the standard library `venv`_ tool);
|
||
* installs all dependencies and also installs HTTPie
|
||
(in editable mode so that the ``http`` command will point to your
|
||
working copy).
|
||
* and runs tests (It is the same as running ``make install test``).
|
||
|
||
|
||
.. code-block:: bash
|
||
|
||
make
|
||
|
||
|
||
|
||
Python virtual environment
|
||
**************************
|
||
|
||
Activate the Python virtual environment—created via the ``make install``
|
||
task during `setup`_—for your active shell session using the following command:
|
||
|
||
.. code-block:: bash
|
||
|
||
source venv/bin/activate
|
||
|
||
(If you use ``virtualenvwrapper``, you can also use ``workon httpie`` to
|
||
activate the environment — we have created a symlink for you. It’s a bit of
|
||
a hack but it works™.)
|
||
|
||
You should now see ``(httpie)`` next to your shell prompt, and
|
||
the ``http`` should point to you development copy:
|
||
|
||
.. code-block::
|
||
|
||
(httpie) ~/Code/httpie $ which http
|
||
/Users/jakub/Code/httpie/venv/bin/http
|
||
(httpie) ~/Code/httpie $ http --version
|
||
2.0.0-dev
|
||
|
||
(Btw, you don’t need to activate the virtual environment if you just want
|
||
run some of the ``make`` tasks. You can also invoke the development
|
||
version of HTTPie directly with ``./venv/bin/http`` without having to activate
|
||
the environment first. The same goes for ``./venv/bin/py.test``, etc.).
|
||
|
||
|
||
Making Changes
|
||
--------------
|
||
|
||
Please make sure your changes conform to `Style Guide for Python Code`_ (PEP8)
|
||
and that ``make pycodestyle`` passes.
|
||
|
||
|
||
Testing & CI
|
||
------------
|
||
|
||
Please add tests for any new features and bug fixes.
|
||
|
||
When you open a pull request,
|
||
`Github Actions <https://github.com/jakubroztocil/httpie/actions>`_
|
||
will automatically run HTTPie’s `test suite`_ against your code
|
||
so please make sure all checks pass.
|
||
|
||
|
||
Running tests locally
|
||
*********************
|
||
|
||
HTTPie uses the `pytest`_ runner. It also uses `Tox`_ which allows you to run
|
||
tests on multiple Python versions even when testing locally.
|
||
|
||
|
||
.. code-block:: bash
|
||
|
||
# Run tests on the current Python interpreter with coverage.
|
||
make test
|
||
|
||
# Run tests with coverage
|
||
make test-cover
|
||
|
||
# Run all tests in all of the supported and available Pythons via Tox
|
||
make test-tox
|
||
|
||
# Test PEP8 compliance
|
||
make pycodestyle
|
||
|
||
# Run extended tests — for code as well as .rst files syntax, packaging, etc.
|
||
make test-all
|
||
|
||
|
||
Running specific tests
|
||
**********************
|
||
|
||
After you have activated your virtual environment (see `setup`_), you
|
||
can run specific tests from the terminal:
|
||
|
||
.. code-block:: bash
|
||
|
||
# Run specific tests on the current Python
|
||
py.test tests/test_uploads.py
|
||
py.test tests/test_uploads.py::TestMultipartFormDataFileUpload
|
||
py.test tests/test_uploads.py::TestMultipartFormDataFileUpload::test_upload_ok
|
||
|
||
# Run specific tests on the on all Pythons via Tox
|
||
# (change to `tox -e py37' to limit Python version)
|
||
tox -- tests/test_uploads.py --verbose
|
||
tox -- tests/test_uploads.py::TestMultipartFormDataFileUpload --verbose
|
||
tox -- tests/test_uploads.py::TestMultipartFormDataFileUpload::test_upload_ok --verbose
|
||
|
||
-----
|
||
|
||
See `Makefile`_ for additional development utilities.
|
||
|
||
|
||
Finally, don't forget to add yourself to `AUTHORS`_!
|
||
|
||
|
||
.. _Tox: http://tox.testrun.org
|
||
.. _supported Python environments: https://github.com/jakubroztocil/httpie/blob/master/tox.ini
|
||
.. _existing issues: https://github.com/jakubroztocil/httpie/issues?state=open
|
||
.. _AUTHORS: https://github.com/jakubroztocil/httpie/blob/master/AUTHORS.rst
|
||
.. _Makefile: https://github.com/jakubroztocil/httpie/blob/master/Makefile
|
||
.. _venv: https://docs.python.org/3/library/venv.html
|
||
.. _pytest: https://pytest.org/
|
||
.. _Style Guide for Python Code: https://python.org/dev/peps/pep-0008/
|
||
.. _test suite: https://github.com/jakubroztocil/httpie/tree/master/tests
|