httpx/docs/contributing.md

Contributing

Thank you for being interested in contributing with HTTPX. There are many ways you can contribute with the project:

• Try HTTPX and report bugs/issues you find
• Implement new features
• Review Pull Requests of others
• Write documentation
• Participate in discussions

Reporting Bugs or Other Issues

Found something that HTTPX should support? Stumbled upon some unexpected behavior?

Feel free to open an issue at the issue tracker. Try to be more descriptive as you can and in case of a bug report, provide as much information as possible like:

• OS platform
• Python version
• Installed dependencies and versions (python -m pip freeze)
• Code snippet
• Error traceback

Development

To start developing HTTPX create a fork of the HTTPX repository on GitHub.

Then clone your fork with the following command replacing YOUR-USERNAME with your GitHub username:

$ git clone https://github.com/YOUR-USERNAME/httpx

With the repository cloned you can access its folder, set up the virtual environment, install the project requirements, and then install HTTPX on edit mode:

$ cd httpx
$ python3 -m venv venv
$ source venv/bin/activate
$ pip install -r test-requirements.txt
$ pip install -e .

!!! note Feel free to replace this step with your development environment setup (pyenv, pipenv, virtualenvwrapper, docker, etc).

Testing and Linting

We use nox to automate testing, linting, and documentation building workflow. Make sure you have it installed at your system before starting.

Install nox with:

$ python3 -m pip install --user nox

Alternatively, use pipx if you prefer to keep it into an isolated environment:

$ pipx install nox

Now, with nox installed run the complete pipeline with:

$ nox

!!! warning The test suite spawns a testing server at the port 8000. Make sure this isn't being used, so the tests can run properly.

To run the code auto-formatting separately:

$ nox -s lint

Also, if you need to run the tests only:

$ nox -s test

You can also run a single test script like this:

$ nox -s test -- tests/test_multipart.py

Documenting

To work with the documentation, make sure you have mkdocs and mkdocs-material installed on your environment:

$ pip install mkdocs mkdocs-material

To spawn the docs server run:

$ mkdocs serve

Releasing

This section is targeted at HTTPX maintainers.

Before releasing a new version, create a pull request that includes:

• An update to the changelog:
  • We follow the format from keepachangelog.
  • Compare master with the tag of the latest release, and list all entries that are of interest to our users:
    • Things that must go in the changelog: added, changed, deprecated or removed features, and bug fixes.
    • Things that should not go in the changelog: changes to documentation, tests or tooling.
    • Try sorting entries in descending order of impact / importance.
    • Keep it concise and to-the-point. 🎯
• A version bump: see __version__.py.

For an example, see #362.

Once the release PR is merged, run $ scripts/publish to publish the new release to PyPI.