From 7c08af7b23e7da69ba9689a4fd30ea539c4aaae2 Mon Sep 17 00:00:00 2001 From: John Litborn <11260241+jakkdl@users.noreply.github.com> Date: Mon, 26 Aug 2024 07:15:01 +0200 Subject: [PATCH] contributing.rst: add instructions for creating virtualenv, update instructions for running w/ coverage (#3036) * add instructions for creating virtualenv, update instructions for running with coverage * fixes after review * okay now instructions actually work --- docs/source/contributing.rst | 35 +++++++++++++++++++++++++++++------ 1 file changed, 29 insertions(+), 6 deletions(-) diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst index f37f57d5dd..cace2943d2 100644 --- a/docs/source/contributing.rst +++ b/docs/source/contributing.rst @@ -176,6 +176,24 @@ This keeps us closer to the desired state where each open issue reflects some work that still needs to be done. +Environment +~~~~~~~~~~~ +We strongly suggest using a virtual environment for managing dependencies, +for example with `venv `__. So to +set up your environment and install dependencies, you should run something like: + +.. code-block:: shell + + cd path/to/trio/checkout/ + python -m venv .venv # create virtual env in .venv + source .venv/bin/activate # activate it + pip install -e . # install trio, needed for pytest plugin + pip install -r test-requirements.txt # install test requirements + +you rarely need to recreate the virtual environment, but you need to re-activate it +in future terminals. You might also need to re-install from test-requirements.txt if +the versions in it get updated. + .. _pull-request-tests: Tests @@ -186,12 +204,11 @@ locally, you should run: .. code-block:: shell - cd path/to/trio/checkout/ - pip install -r test-requirements.txt # possibly using a virtualenv - pytest trio + source .venv/bin/activate # if not already activated + pytest src This doesn't try to be completely exhaustive – it only checks that -things work on your machine, and it may skip some slow tests. But it's +things work on your machine, and it will skip some slow tests. But it's a good way to quickly check that things seem to be working, and we'll automatically run the full test suite when your PR is submitted, so you'll have a chance to see and fix any remaining issues then. @@ -211,8 +228,14 @@ it being merely hard to fix). For example: We use Codecov to track coverage, because it makes it easy to combine coverage from running in different configurations. Running coverage locally can be useful -(``pytest --cov=PACKAGENAME --cov-report=html``), but don't be -surprised if you get lower coverage than when looking at Codecov + +.. code-block:: shell + + coverage run -m pytest + coverage combine + coverage report + +but don't be surprised if you get lower coverage than when looking at Codecov reports, because there are some lines that are only executed on Windows, or macOS, or PyPy, or CPython, or... you get the idea. After you create a PR, Codecov will automatically report back with the