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