From: Tom Christie Date: Wed, 24 Mar 2021 16:48:57 +0000 (+0000) Subject: Refine project workflow (#1534) X-Git-Tag: 0.18.0~29 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=437b55c5202a034e8e5fdce4be1b96198d33be31;p=thirdparty%2Fhttpx.git Refine project workflow (#1534) * Refine project workflow * Fix link to third party packages --- diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 00000000..e1a953dc --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,235 @@ +# 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. + +

+ Failing PR commit status +

+ +Here are some common ways the test suite can fail: + +### Check Job Failed + +

+ Failing GitHub action lint job +

+ +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 + +

+ Failing GitHub action test job +

+ +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` diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml new file mode 100644 index 00000000..2f87d94c --- /dev/null +++ b/.github/FUNDING.yml @@ -0,0 +1 @@ +github: encode diff --git a/.github/ISSUE_TEMPLATE/1-issue.md b/.github/ISSUE_TEMPLATE/1-issue.md new file mode 100644 index 00000000..b0cb848a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/1-issue.md @@ -0,0 +1,15 @@ +--- +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 #... diff --git a/.github/ISSUE_TEMPLATE/2-bug-report.md b/.github/ISSUE_TEMPLATE/2-bug-report.md deleted file mode 100644 index a2060307..00000000 --- a/.github/ISSUE_TEMPLATE/2-bug-report.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -name: Bug report -about: Report a bug to help improve this project ---- - -### Checklist - - - -- [ ] 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 - - - -### To reproduce - - - -### Expected behavior - - - -### Actual behavior - - - -### Debugging material - - - -### Environment - -- OS: -- Python version: -- HTTPX version: -- Async environment: -- HTTP proxy: -- Custom certificates: - -### Additional context - - diff --git a/.github/ISSUE_TEMPLATE/3-feature-request.md b/.github/ISSUE_TEMPLATE/3-feature-request.md deleted file mode 100644 index a4237e28..00000000 --- a/.github/ISSUE_TEMPLATE/3-feature-request.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -name: Feature request -about: Suggest an idea for this project. ---- - -### Checklist - - - -- [ ] 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. - - - -## Describe the solution you would like. - - - -## Describe alternatives you considered - - - -## Additional context - - - diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 2ad6e8e2..b45ca757 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,7 +1,11 @@ # 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. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000..13b7dfe1 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,9 @@ +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 #... diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 73a8b3db..00000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,5 +0,0 @@ -#### 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. diff --git a/docs/code_of_conduct.md b/docs/code_of_conduct.md new file mode 100644 index 00000000..16472898 --- /dev/null +++ b/docs/code_of_conduct.md @@ -0,0 +1,56 @@ +# 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/). diff --git a/docs/contributing.md b/docs/contributing.md index 9732c810..e1a953dc 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -12,10 +12,13 @@ There are many ways you can contribute to the project: ## 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: @@ -25,6 +28,15 @@ 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 diff --git a/docs/index.md b/docs/index.md index 3da239f7..3fcb3361 100644 --- a/docs/index.md +++ b/docs/index.md @@ -101,7 +101,7 @@ the [async support](async.md) section, or the [HTTP/2](http2.md) section. 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 diff --git a/docs/third-party-packages.md b/docs/third_party_packages.md similarity index 100% rename from docs/third-party-packages.md rename to docs/third_party_packages.md diff --git a/mkdocs.yml b/mkdocs.yml index ccafcac1..4bcc4d75 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -20,8 +20,9 @@ nav: - 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