From a0616aebf222b2c3995362521ecb8bb44cec5c64 Mon Sep 17 00:00:00 2001 From: jakkdl Date: Wed, 17 Jul 2024 15:36:11 +0200 Subject: [PATCH 1/3] add instructions for creating virtualenv, update instructions for running with coverage --- docs/source/contributing.rst | 30 ++++++++++++++++++++++++++---- 1 file changed, 26 insertions(+), 4 deletions(-) diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst index f37f57d5dd..2c867d7b5c 100644 --- a/docs/source/contributing.rst +++ b/docs/source/contributing.rst @@ -176,6 +176,23 @@ 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 -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,8 +203,7 @@ locally, you should run: .. code-block:: shell - cd path/to/trio/checkout/ - pip install -r test-requirements.txt # possibly using a virtualenv + source .venv/bin/activate # if not already activated pytest trio This doesn't try to be completely exhaustive – it only checks that @@ -211,8 +227,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 From 28cab842b2b153f3c03d6948c8cf29044b04d065 Mon Sep 17 00:00:00 2001 From: jakkdl Date: Sun, 25 Aug 2024 12:43:45 +0200 Subject: [PATCH 2/3] fixes after review --- docs/source/contributing.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst index 2c867d7b5c..57450099a2 100644 --- a/docs/source/contributing.rst +++ b/docs/source/contributing.rst @@ -187,7 +187,8 @@ set up your environment and install dependencies, you should run something like: cd path/to/trio/checkout/ python -m venv .venv # create virtual env in .venv source .venv/bin/activate # activate it - pip install -r test-requirements.txt install test requirements + pip install -e . + 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 From fa4cd94dd5405cf54953fed3426377aac901826a Mon Sep 17 00:00:00 2001 From: jakkdl Date: Sun, 25 Aug 2024 12:52:04 +0200 Subject: [PATCH 3/3] okay now instructions actually work --- docs/source/contributing.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst index 57450099a2..cace2943d2 100644 --- a/docs/source/contributing.rst +++ b/docs/source/contributing.rst @@ -187,7 +187,7 @@ set up your environment and install dependencies, you should run something like: cd path/to/trio/checkout/ python -m venv .venv # create virtual env in .venv source .venv/bin/activate # activate it - pip install -e . + 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 @@ -205,10 +205,10 @@ locally, you should run: .. code-block:: shell source .venv/bin/activate # if not already activated - pytest trio + 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.