1# Contributing to HTTPie 2 3Bug reports and code and documentation patches are welcome. You can 4help this project also by using the development version of HTTPie 5and by reporting any bugs you might encounter. 6 7## 1. Reporting bugs 8 9**It's important that you provide the full command argument list 10as well as the output of the failing command.** 11 12Use the `--debug` flag and copy&paste both the command and its output 13to your bug report, e.g.: 14 15```bash 16$ http --debug <COMPLETE ARGUMENT LIST THAT TRIGGERS THE ERROR> 17<COMPLETE OUTPUT> 18``` 19 20## 2. Contributing Code and Docs 21 22Before working on a new feature or a bug, please browse [existing issues](https://github.com/httpie/httpie/issues) 23to see whether it has previously been discussed. 24 25If your change alters HTTPie’s behaviour or interface, it's a good idea to 26discuss it before you start working on it. 27 28If you are fixing an issue, the first step should be to create a test case that 29reproduces the incorrect behaviour. That will also help you to build an 30understanding of the issue at hand. 31 32**Pull requests introducing code changes without tests 33will generally not get merged. The same goes for PRs changing HTTPie’s 34behaviour and not providing documentation.** 35 36Conversely, PRs consisting of documentation improvements or tests 37for existing-yet-previously-untested behavior will very likely be merged. 38Therefore, docs and tests improvements are a great candidate for your first 39contribution. 40 41Consider also adding a [CHANGELOG](https://github.com/httpie/httpie/blob/master/CHANGELOG.md) entry for your changes. 42 43### Development Environment 44 45#### Getting the code 46 47Go to <https://github.com/httpie/httpie> and fork the project repository. 48 49```bash 50# Clone your fork 51$ git clone git@github.com:<YOU>/httpie.git 52 53# Enter the project directory 54$ cd httpie 55 56# Create a branch for your changes 57$ git checkout -b my_topical_branch 58``` 59 60#### Setup 61 62The [Makefile](https://github.com/httpie/httpie/blob/master/Makefile) contains a bunch of tasks to get you started. Just run 63the following command, which: 64 65- Creates an isolated Python virtual environment inside `./venv` 66 (via the standard library [venv](https://docs.python.org/3/library/venv.html) tool); 67- installs all dependencies and also installs HTTPie 68 (in editable mode so that the `http` command will point to your 69 working copy). 70- and runs tests (It is the same as running `make install test`). 71 72```bash 73$ make 74``` 75 76#### Python virtual environment 77 78Activate the Python virtual environment—created via the `make install` 79task during [setup](#setup) for your active shell session using the following command: 80 81```bash 82$ source venv/bin/activate 83``` 84 85(If you use `virtualenvwrapper`, you can also use `workon httpie` to 86activate the environment — we have created a symlink for you. It’s a bit of 87a hack but it works™.) 88 89You should now see `(httpie)` next to your shell prompt, and 90the `http` command should point to your development copy: 91 92```bash 93(httpie) ~/Code/httpie $ which http 94/Users/<user>/Code/httpie/venv/bin/http 95(httpie) ~/Code/httpie $ http --version 962.0.0-dev 97``` 98 99(Btw, you don’t need to activate the virtual environment if you just want 100run some of the `make` tasks. You can also invoke the development 101version of HTTPie directly with `./venv/bin/http` without having to activate 102the environment first. The same goes for `./venv/bin/pytest`, etc.). 103 104### Making Changes 105 106Please make sure your changes conform to [Style Guide for Python Code](https://python.org/dev/peps/pep-0008/) (PEP8) 107and that `make pycodestyle` passes. 108 109### Testing & CI 110 111Please add tests for any new features and bug fixes. 112 113When you open a Pull Request, [GitHub Actions](https://github.com/httpie/httpie/actions) will automatically run HTTPie’s [test suite](https://github.com/httpie/httpie/tree/master/tests) against your code, so please make sure all checks pass. 114 115#### Running tests locally 116 117HTTPie uses the [pytest](https://pytest.org/) runner. 118 119```bash 120# Run tests on the current Python interpreter with coverage. 121$ make test 122 123# Run tests with coverage 124$ make test-cover 125 126# Test PEP8 compliance 127$ make codestyle 128 129# Run extended tests — for code as well as .md files syntax, packaging, etc. 130$ make test-all 131``` 132 133#### Running specific tests 134 135After you have activated your virtual environment (see [setup](#setup)), you 136can run specific tests from the terminal: 137 138```bash 139# Run specific tests on the current Python 140$ python -m pytest tests/test_uploads.py 141$ python -m pytest tests/test_uploads.py::TestMultipartFormDataFileUpload 142$ python -m pytest tests/test_uploads.py::TestMultipartFormDataFileUpload::test_upload_ok 143``` 144 145See [Makefile](https://github.com/httpie/httpie/blob/master/Makefile) for additional development utilities. 146 147#### Windows 148 149If you are on a Windows machine and not able to run `make`, 150follow the next steps for a basic setup. As a prerequisite, you need to have 151Python 3.6+ installed. 152 153Create a virtual environment and activate it: 154 155```powershell 156C:\> python -m venv --prompt httpie venv 157C:\> venv\Scripts\activate 158``` 159 160Install HTTPie in editable mode with all the dependencies: 161 162```powershell 163C:\> python -m pip install --upgrade -e . -r requirements-dev.txt 164``` 165 166You should now see `(httpie)` next to your shell prompt, and 167the `http` command should point to your development copy: 168 169```powershell 170# In PowerShell: 171(httpie) PS C:\Users\ovezovs\httpie> Get-Command http 172CommandType Name Version Source 173----------- ---- ------- ------ 174Application http.exe 0.0.0.0 C:\Users\ovezovs\httpie\venv\Scripts\http.exe 175``` 176 177```bash 178# In CMD: 179(httpie) C:\Users\ovezovs\httpie> where http 180C:\Users\ovezovs\httpie\venv\Scripts\http.exe 181C:\Users\ovezovs\AppData\Local\Programs\Python\Python38-32\Scripts\http.exe 182 183(httpie) C:\Users\ovezovs\httpie> http --version 1842.3.0-dev 185``` 186 187Use `pytest` to run tests locally with an active virtual environment: 188 189```bash 190# Run all tests 191$ python -m pytest 192``` 193 194______________________________________________________________________ 195 196Finally, feel free to add yourself to [AUTHORS](https://github.com/httpie/httpie/blob/master/AUTHORS.md)! 197