Skip to content

Latest commit

 

History

History
183 lines (117 loc) · 5.12 KB

CONTRIBUTING.rst

File metadata and controls

183 lines (117 loc) · 5.12 KB
Raw

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.:

$ 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.

# 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).
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:

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:

(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 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.

# 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:

# 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!