Add hints for debugging CI issues (#399)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644 (file)
index 0000000..73a8b3d
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,5 @@
+#### 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/contributing.md b/docs/contributing.md
index ca569e817bbde30e8f164e82ac796be1e123239a..2faf88f684076806e06b9a3318536b59bf46b15b 100644 (file)
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -110,6 +110,55 @@ To run the documentation site locally (useful for previewing changes), use:
 $ nox -s serve
 ```
 
+## Resolving Build / Travis 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/travis-fail.png" alt='Failing PR commit status'>
+</p>
+
+Here are some common ways the test suite can fail:
+
+### NOX_SESSION=check Job Failed
+
+<p align="center" style="margin: 0 0 10px">
+  <img src="https://raw.githubusercontent.com/encode/httpx/master/docs/img/travis-fail-check.png" alt='Failing Travis 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:
+
+`nox -s check`
+
+It may be worth it to run `nox -s lint` to attempt auto-formatting the code
+and if that job succeeds commit the changes.
+
+### NOX_SESSION=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`.
+
+### NOX_SESSION=test-3.X Job Failed
+
+<p align="center" style="margin: 0 0 10px">
+  <img src="https://raw.githubusercontent.com/encode/httpx/master/docs/img/travis-fail-test.png" alt='Failing Travis 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 isn't 100% you will see this message under the coverage report:
+
+`FAIL Required test coverage of 100% not reached. Total coverage: 99.00%`
+
+Look at the [coverage report from codecov](https://codecov.io/gh/encode/httpx/pulls)
+for the pull request for help debugging coverage.
+
 ## Releasing
 
 *This section is targeted at HTTPX maintainers.*

diff --git a/docs/img/travis-fail-check.png b/docs/img/travis-fail-check.png
new file mode 100644 (file)
index 0000000..4049e8f
Binary files /dev/null and b/docs/img/travis-fail-check.png differ

diff --git a/docs/img/travis-fail-test.png b/docs/img/travis-fail-test.png
new file mode 100644 (file)
index 0000000..018d1a9
Binary files /dev/null and b/docs/img/travis-fail-test.png differ

diff --git a/docs/img/travis-fail.png b/docs/img/travis-fail.png
new file mode 100644 (file)
index 0000000..dc85f4a
Binary files /dev/null and b/docs/img/travis-fail.png differ