--- /dev/null
+# Contributing
+
+Thank you for being interested in contributing to HTTPX.
+There are many ways you can contribute to the project:
+
+- Try HTTPX and [report bugs/issues you find](https://github.com/encode/httpx/issues/new)
+- [Implement new features](https://github.com/encode/httpx/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
+- [Review Pull Requests of others](https://github.com/encode/httpx/pulls)
+- Write documentation
+- Participate in discussions
+
+## Reporting Bugs or Other Issues
+
+Found something that HTTPX should support?
+Stumbled upon some unexpected behaviour?
+
+Contributions should generally start out with [a discussion](https://github.com/encode/httpx/discussions).
+Possible bugs may be raised as a "Potential Issue" discussion, feature requests may
+be raised as an "Ideas" discussion. We can then determine if the discussion needs
+to be escalated into an "Issue" or not, or if we'd consider a pull request.
+
+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
+
+You should always try to reduce any examples to the *simplest possible case*
+that demonstrates the issue.
+
+Some possibly useful tips for narrowing down potential issues...
+
+- Does the issue exist on HTTP/1.1, or HTTP/2, or both?
+- Does the issue exist with `Client`, `AsyncClient`, or both?
+- When using `AsyncClient` does the issue exist when using `asyncio` or `trio`, or both?
+
+## Development
+
+To start developing HTTPX create a **fork** of the
+[HTTPX repository](https://github.com/encode/httpx) on GitHub.
+
+Then clone your fork with the following command replacing `YOUR-USERNAME` with
+your GitHub username:
+
+```shell
+$ git clone https://github.com/YOUR-USERNAME/httpx
+```
+
+You can now install the project and its dependencies using:
+
+```shell
+$ cd httpx
+$ scripts/install
+```
+
+## Testing and Linting
+
+We use custom shell scripts to automate testing, linting,
+and documentation building workflow.
+
+To run the tests, use:
+
+```shell
+$ scripts/test
+```
+
+!!! warning
+ The test suite spawns testing servers on ports **8000** and **8001**.
+ Make sure these are not in use, so the tests can run properly.
+
+You can run a single test script like this:
+
+```shell
+$ scripts/test -- tests/test_multipart.py
+```
+
+To run the code auto-formatting:
+
+```shell
+$ scripts/lint
+```
+
+Lastly, to run code checks separately (they are also run as part of `scripts/test`), run:
+
+```shell
+$ scripts/check
+```
+
+## Documenting
+
+Documentation pages are located under the `docs/` folder.
+
+To run the documentation site locally (useful for previewing changes), use:
+
+```shell
+$ scripts/docs
+```
+
+## Resolving Build / CI Failures
+
+Once you've submitted your pull request, the test suite will automatically run, and the results will show up in GitHub.
+If the test suite fails, you'll want to click through to the "Details" link, and try to identify why the test suite failed.
+
+<p align="center" style="margin: 0 0 10px">
+ <img src="https://raw.githubusercontent.com/encode/httpx/master/docs/img/gh-actions-fail.png" alt='Failing PR commit status'>
+</p>
+
+Here are some common ways the test suite can fail:
+
+### Check Job Failed
+
+<p align="center" style="margin: 0 0 10px">
+ <img src="https://raw.githubusercontent.com/encode/httpx/master/docs/img/gh-actions-fail-check.png" alt='Failing GitHub action lint job'>
+</p>
+
+This job failing means there is either a code formatting issue or type-annotation issue.
+You can look at the job output to figure out why it's failed or within a shell run:
+
+```shell
+$ scripts/check
+```
+
+It may be worth it to run `$ scripts/lint` to attempt auto-formatting the code
+and if that job succeeds commit the changes.
+
+### Docs Job Failed
+
+This job failing means the documentation failed to build. This can happen for
+a variety of reasons like invalid markdown or missing configuration within `mkdocs.yml`.
+
+### Python 3.X Job Failed
+
+<p align="center" style="margin: 0 0 10px">
+ <img src="https://raw.githubusercontent.com/encode/httpx/master/docs/img/gh-actions-fail-test.png" alt='Failing GitHub action test job'>
+</p>
+
+This job failing means the unit tests failed or not all code paths are covered by unit tests.
+
+If tests are failing you will see this message under the coverage report:
+
+`=== 1 failed, 435 passed, 1 skipped, 1 xfailed in 11.09s ===`
+
+If tests succeed but coverage doesn't reach our current threshold, you will see this
+message under the coverage report:
+
+`FAIL Required test coverage of 100% not reached. Total coverage: 99.00%`
+
+## 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](https://keepachangelog.com/en/1.0.0/).
+ - [Compare](https://github.com/encode/httpx/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 [#1006](https://github.com/encode/httpx/pull/1006).
+
+Once the release PR is merged, create a
+[new release](https://github.com/encode/httpx/releases/new) including:
+
+- Tag version like `0.13.3`.
+- Release title `Version 0.13.3`
+- Description copied from the changelog.
+
+Once created this release will be automatically uploaded to PyPI.
+
+If something goes wrong with the PyPI job the release can be published using the
+`scripts/publish` script.
+
+## Development proxy setup
+
+To test and debug requests via a proxy it's best to run a proxy server locally.
+Any server should do but HTTPCore's test suite uses
+[`mitmproxy`](https://mitmproxy.org/) which is written in Python, it's fully
+featured and has excellent UI and tools for introspection of requests.
+
+You can install `mitmproxy` using `pip install mitmproxy` or [several
+other ways](https://docs.mitmproxy.org/stable/overview-installation/).
+
+`mitmproxy` does require setting up local TLS certificates for HTTPS requests,
+as its main purpose is to allow developers to inspect requests that pass through
+it. We can set them up follows:
+
+1. [`pip install trustme-cli`](https://github.com/sethmlarson/trustme-cli/).
+2. `trustme-cli -i example.org www.example.org`, assuming you want to test
+connecting to that domain, this will create three files: `server.pem`,
+`server.key` and `client.pem`.
+3. `mitmproxy` requires a PEM file that includes the private key and the
+certificate so we need to concatenate them:
+`cat server.key server.pem > server.withkey.pem`.
+4. Start the proxy server `mitmproxy --certs server.withkey.pem`, or use the
+[other mitmproxy commands](https://docs.mitmproxy.org/stable/) with different
+UI options.
+
+At this point the server is ready to start serving requests, you'll need to
+configure HTTPX as described in the
+[proxy section](https://www.python-httpx.org/advanced/#http-proxying) and
+the [SSL certificates section](https://www.python-httpx.org/advanced/#ssl-certificates),
+this is where our previously generated `client.pem` comes in:
+
+```
+import httpx
+
+proxies = {"all": "http://127.0.0.1:8080/"}
+
+with httpx.Client(proxies=proxies, verify="/path/to/client.pem") as client:
+ response = client.get("https://example.org")
+ print(response.status_code) # should print 200
+```
+
+Note, however, that HTTPS requests will only succeed to the host specified
+in the SSL/TLS certificate we generated, HTTPS requests to other hosts will
+raise an error like:
+
+```
+ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate
+verify failed: Hostname mismatch, certificate is not valid for
+'duckduckgo.com'. (_ssl.c:1108)
+```
+
+If you want to make requests to more hosts you'll need to regenerate the
+certificates and include all the hosts you intend to connect to in the
+seconds step, i.e.
+
+`trustme-cli -i example.org www.example.org duckduckgo.com www.duckduckgo.com`
--- /dev/null
+github: encode
--- /dev/null
+---
+name: Issue
+about: Please only raise an issue if you've been advised to do so after discussion. Thanks! 🙏
+---
+
+The starting point for issues should usually be [a discussion](https://github.com/encode/httpx/discussions)
+
+Possible bugs may be raised as a "Potential Issue" discussion, feature requests may
+be raised as an "Ideas" discussion. We can then determine if the discussion needs
+to be escalated into an "Issue" or not.
+
+This will help us ensure that the "Issues" list properly reflects ongoing or needed
+work on the project.
+
+- [ ] Initially raised as discussion #...
+++ /dev/null
----
-name: Bug report
-about: Report a bug to help improve this project
----
-
-### Checklist
-
-<!-- Please make sure you check all these items before submitting your bug report. -->
-
-- [ ] The bug is reproducible against the latest release and/or `master`.
-- [ ] There are no similar issues or pull requests to fix it yet.
-
-### Describe the bug
-
-<!-- A clear and concise description of what the bug is. -->
-
-### To reproduce
-
-<!-- Provide a *minimal* example with steps to reproduce the bug locally.
-
-NOTE: try to keep any external dependencies *at an absolute minimum* (servers, proxies, certificates...).
-In other words, remove anything that doesn't make the bug go away.
-
-If you need a local server to replicate against, you can build one using eg. Starlette [0] and Uvicorn [1], or any tool you feel comfortable with. Check out other issues for examples and remember to share setup instructions here. :-)
-
-[0]: https://www.starlette.io
-[1]: https://www.uvicorn.org
--->
-
-### Expected behavior
-
-<!-- A clear and concise description of what you expected to happen. -->
-
-### Actual behavior
-
-<!-- A clear and concise description of what actually happens. -->
-
-### Debugging material
-
-<!-- Any tracebacks, screenshots, etc. that can help understanding the problem.
-
-NOTE:
-- Please list tracebacks in full (don't truncate them).
-- If relevant, consider turning on DEBUG or TRACE logs for additional details (see https://www.python-httpx.org/environment_variables/#httpx_log_level).
-- Consider using `<details>` to make tracebacks/logs collapsible if they're very large (see https://gist.github.com/ericclemmons/b146fe5da72ca1f706b2ef72a20ac39d).
--->
-
-### Environment
-
-- OS: <!-- eg Linux/Windows/macOS. -->
-- Python version: <!-- eg 3.8.2 (get it with `$ python -V`). -->
-- HTTPX version: <!-- eg 0.12.0 (get it with `$ pip show httpx`). -->
-- Async environment: <!-- eg asyncio/trio. If using asyncio, include whether the bug reproduces on trio (and vice versa). -->
-- HTTP proxy: <!-- yes/no, if yes please try reproducing without it. -->
-- Custom certificates: <!-- yes/no, if yes please try reproducing without them. If the bug is related to SSL/TLS, you can setup HTTPS on a local server using these instructions: https://www.python-httpx.org/advanced/#making-https-requests-to-a-local-server. -->
-
-### Additional context
-
-<!-- Any additional information that can help understanding the problem.
-
-Eg. linked issues, or a description of what you were trying to achieve. -->
+++ /dev/null
----
-name: Feature request
-about: Suggest an idea for this project.
----
-
-### Checklist
-
-<!-- Please make sure you check all these items before submitting your feature request. -->
-
-- [ ] There are no similar issues or pull requests for this yet.
-- [ ] I discussed this idea on the [community chat](https://gitter.im/encode/community) and feedback is positive.
-
-### Is your feature related to a problem? Please describe.
-
-<!-- A clear and concise description of what you are trying to achieve.
-
-Eg "I want to be able to [...] but I can't because [...]". -->
-
-## Describe the solution you would like.
-
-<!-- A clear and concise description of what you would want to happen.
-
-For API changes, try to provide a code snippet of what you would like the API to look like.
--->
-
-## Describe alternatives you considered
-
-<!-- Please describe any alternative solutions or features you've considered to solve
-your problem and why they wouldn't solve it. -->
-
-## Additional context
-
-<!-- Provide any additional context, screenshots, tracebacks, etc. about the feature here. -->
-
# Ref: https://help.github.com/en/github/building-a-strong-community/configuring-issue-templates-for-your-repository#configuring-the-template-chooser
blank_issues_enabled: true
contact_links:
-- name: Question
+- name: Discussions
+ url: https://github.com/encode/httpx/discussions
+ about: >
+ The "Discussions" forum is where you want to start. 💖
+- name: Chat
url: https://gitter.im/encode/community
about: >
- Ask a question
+ Our community chat forum.
--- /dev/null
+The starting point for contributions should usually be [a discussion](https://github.com/encode/httpx/discussions)
+
+Simple documentation typos may be raised as stand-alone pull requests, but otherwise
+please ensure you've discussed the your proposal prior to issuing a pull request.
+
+This will help us direct work appropriately, and ensure that any suggested changes
+have been okayed by the maintainers.
+
+- [ ] Initially raised as discussion #...
+++ /dev/null
-#### Thanks for considering contributing to HTTPX!
-
-Our [documentation on contributing to HTTPX](https://www.encode.io/httpx/contributing/)
-contains information on how to report bugs, write and test new features, and
-debug issues with your own changes.
--- /dev/null
+# Code of Conduct
+
+We expect contributors to our projects and online spaces to follow [the Python Software Foundation’s Code of Conduct](https://www.python.org/psf/conduct/).
+
+The Python community is made up of members from around the globe with a diverse set of skills, personalities, and experiences. It is through these differences that our community experiences great successes and continued growth. When you're working with members of the community, this Code of Conduct will help steer your interactions and keep Python a positive, successful, and growing community.
+
+## Our Community
+
+Members of the Python community are **open, considerate, and respectful**. Behaviours that reinforce these values contribute to a positive environment, and include:
+
+* **Being open.** Members of the community are open to collaboration, whether it's on PEPs, patches, problems, or otherwise.
+* **Focusing on what is best for the community.** We're respectful of the processes set forth in the community, and we work within them.
+* **Acknowledging time and effort.** We're respectful of the volunteer efforts that permeate the Python community. We're thoughtful when addressing the efforts of others, keeping in mind that often times the labor was completed simply for the good of the community.
+* **Being respectful of differing viewpoints and experiences.** We're receptive to constructive comments and criticism, as the experiences and skill sets of other members contribute to the whole of our efforts.
+* **Showing empathy towards other community members.** We're attentive in our communications, whether in person or online, and we're tactful when approaching differing views.
+* **Being considerate.** Members of the community are considerate of their peers -- other Python users.
+* **Being respectful.** We're respectful of others, their positions, their skills, their commitments, and their efforts.
+* **Gracefully accepting constructive criticism.** When we disagree, we are courteous in raising our issues.
+* **Using welcoming and inclusive language.** We're accepting of all who wish to take part in our activities, fostering an environment where anyone can participate and everyone can make a difference.
+
+## Our Standards
+
+Every member of our community has the right to have their identity respected. The Python community is dedicated to providing a positive experience for everyone, regardless of age, gender identity and expression, sexual orientation, disability, physical appearance, body size, ethnicity, nationality, race, or religion (or lack thereof), education, or socio-economic status.
+
+## Inappropriate Behavior
+
+Examples of unacceptable behavior by participants include:
+
+* Harassment of any participants in any form
+* Deliberate intimidation, stalking, or following
+* Logging or taking screenshots of online activity for harassment purposes
+* Publishing others' private information, such as a physical or electronic address, without explicit permission
+* Violent threats or language directed against another person
+* Incitement of violence or harassment towards any individual, including encouraging a person to commit suicide or to engage in self-harm
+* Creating additional online accounts in order to harass another person or circumvent a ban
+* Sexual language and imagery in online communities or in any conference venue, including talks
+* Insults, put downs, or jokes that are based upon stereotypes, that are exclusionary, or that hold others up for ridicule
+* Excessive swearing
+* Unwelcome sexual attention or advances
+* Unwelcome physical contact, including simulated physical contact (eg, textual descriptions like "hug" or "backrub") without consent or after a request to stop
+* Pattern of inappropriate social contact, such as requesting/assuming inappropriate levels of intimacy with others
+* Sustained disruption of online community discussions, in-person presentations, or other in-person events
+* Continued one-on-one communication after requests to cease
+* Other conduct that is inappropriate for a professional audience including people of many different backgrounds
+
+Community members asked to stop any inappropriate behavior are expected to comply immediately.
+
+## Enforcement
+
+We take Code of Conduct violations seriously, and will act to ensure our spaces are welcoming, inclusive, and professional environments to communicate in.
+
+If you need to raise a Code of Conduct report, you may do so privately by email to tom@tomchristie.com.
+
+Reports will be treated confidentially.
+
+Alternately you may [make a report to the Python Software Foundation](https://www.python.org/psf/conduct/reporting/).
## Reporting Bugs or Other Issues
Found something that HTTPX should support?
-Stumbled upon some unexpected behavior?
+Stumbled upon some unexpected behaviour?
+
+Contributions should generally start out with [a discussion](https://github.com/encode/httpx/discussions).
+Possible bugs may be raised as a "Potential Issue" discussion, feature requests may
+be raised as an "Ideas" discussion. We can then determine if the discussion needs
+to be escalated into an "Issue" or not, or if we'd consider a pull request.
-Feel free to open an issue at the
-[issue tracker](https://github.com/encode/httpx/issues).
Try to be more descriptive as you can and in case of a bug report,
provide as much information as possible like:
- Code snippet
- Error traceback
+You should always try to reduce any examples to the *simplest possible case*
+that demonstrates the issue.
+
+Some possibly useful tips for narrowing down potential issues...
+
+- Does the issue exist on HTTP/1.1, or HTTP/2, or both?
+- Does the issue exist with `Client`, `AsyncClient`, or both?
+- When using `AsyncClient` does the issue exist when using `asyncio` or `trio`, or both?
+
## Development
To start developing HTTPX create a **fork** of the
The [Developer Interface](api.md) provides a comprehensive API reference.
-To find out about tools that integrate with HTTPX, see [Third Party Packages](third-party-packages.md).
+To find out about tools that integrate with HTTPX, see [Third Party Packages](third_party_packages.md).
## Dependencies
- Developer Interface: 'api.md'
- Exceptions: 'exceptions.md'
- Troubleshooting: 'troubleshooting.md'
- - Third Party Packages: 'third-party-packages.md'
+ - Third Party Packages: 'third_party_packages.md'
- Contributing: 'contributing.md'
+ - Code of Conduct: 'code_of_conduct.md'
markdown_extensions:
- admonition
projects / thirdparty / httpx.git / commitdiff
