From fa85367fc99cb42c4ad9550abf58b411acd5c8be Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Mon, 30 May 2022 23:44:13 +0100 Subject: [PATCH] CONTRIBUTING: improve docs on running tests locally (#7992) Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com> --- CONTRIBUTING.md | 102 ++++++++++++++++++++++++------------------------ 1 file changed, 51 insertions(+), 51 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d441b71fb..2a1477c58 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -26,9 +26,11 @@ it takes a bit longer. For more details, read below. ### Code away! -Typeshed runs continuous integration (CI) on all pull requests. This will -automatically fix formatting (using `black`, `isort`) and run tests. -It means you can ignore all local setup on your side, focus on the +Typeshed runs continuous integration (CI) on all pull requests. This means that +if you file a pull request (PR), our full test suite -- including our linter, +`flake8` -- is run on your PR. It also means that bots will automatically apply +changes to your PR (using `black` and `isort`) to fix any formatting issues. +This frees you up to ignore all local setup on your side, focus on the code and rely on the CI to fix everything, or point you to the places that need fixing. @@ -46,57 +48,75 @@ please refer to this ### Linux/Mac OS -On Linux and Mac OS, you will be able to run the full test suite on Python 3.8 -or 3.9. Running the tests on <=3.7 is not supported, and the pytype tests -[cannot currently be run on Python 3.10](https://github.com/google/pytype/issues/1022). - +On Linux and Mac OS, you will be able to run the full test suite on Python 3.8, +3.9 or 3.10. To install the necessary requirements, run the following commands from a terminal window: ``` -$ python3 -m venv .venv3 -$ source .venv3/bin/activate -(.venv3)$ pip install -U pip -(.venv3)$ pip install -r requirements-tests.txt +$ python3 -m venv .venv +$ source .venv/bin/activate +(.venv)$ pip install -U pip +(.venv)$ pip install -r requirements-tests.txt ``` ### Windows -If you are using a Windows operating system, you will not be able to run the -full test suite. One option is to install +If you are using a Windows operating system, you will not be able to run the pytype +tests, as pytype +[does not currently support running on Windows](https://github.com/google/pytype#requirements). +One option is to install [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/faq), which will allow you to run the full suite of tests. If you choose to install WSL, follow the Linux/Mac OS instructions above. -If you do not wish to install WSL, you will not be able to run the pytype -tests, as pytype -[does not currently support running on Windows](https://github.com/google/pytype#requirements). -However, the upside of this is that you will be able to run all -Windows-compatible tests on Python 3.9, 3.8 or 3.10, as it is only the pytype -tests that cannot currently be run on 3.10. - -To install all non-pytype requirements on Windows without WSL, run the -following commands from a Windows terminal: +If you do not wish to install WSL, run the following commands from a Windows +terminal to install all non-pytype requirements: ``` -> python3 -m venv .venv3 -> ".venv3/Scripts/activate" -(.venv3) > python -m pip install -U pip -(.venv3) > python -m pip install -r requirements-tests.txt +> python -m venv .venv +> ".venv/scripts/activate" +(.venv) > pip install -U pip +(.venv) > pip install -r requirements-tests.txt +``` + +### Optional dependencies + +Several tests also have `termcolor` as an optional dependency. Installing this +is not essential to run the tests, but can make the output of some of the tests +slightly prettier and easier to read. To install `termcolor`, run: + +``` +pip install termcolor ``` ## Code formatting -The code is formatted by `black` and `isort`. +The code is formatted using `black` and `isort`. The repository is equipped with a [`pre-commit.ci`](https://pre-commit.ci/) configuration file. This means that you don't *need* to do anything yourself to run the code formatters. When you push a commit, a bot will run those for you -right away and add a commit to your PR. Neat, no? +right away and add a commit to your PR. -That being said, if you *want* to run the checks locally when you commit, you -can install the hooks: please refer to the [pre-commit](https://pre-commit.com/) -documentation. +That being said, if you *want* to run the checks locally when you commit, +you're free to do so. Either run `black` and `isort` manually... + +``` +isort . +black . +``` + +...Or install the pre-commit hooks: please refer to the +[pre-commit](https://pre-commit.com/) documentation. + +Our code is also linted using `flake8`, with plugins `flake8-pyi` and `flake8-bugbear`. As with our other checks, running +flake8 before filing a PR is not required. However, if you wish to run flake8 +locally, install the test dependencies as outlined above, and then run: + +``` +flake8 . +``` ## Where to make changes @@ -478,26 +498,6 @@ into any of those categories, use your best judgement. * Use `HasX` for protocols that have readable and/or writable attributes or getter/setter methods (e.g. `HasItems`, `HasFileno`). -## Formatting stubs - -Stubs should be reformatted with the formatters -[black](https://github.com/psf/black) and -[isort](https://github.com/PyCQA/isort) before submission. They -should also be checked for common problems by using -[flake8](https://flake8.pycqa.org/en/latest/) and the flake8 plugins -[flake8-pyi](https://github.com/ambv/flake8-pyi) and -[flake8-bugbear](https://github.com/PyCQA/flake8-bugbear). -All of these packages have been installed if you followed the -[setup instructions above](#preparing-the-environment). - -To format and check your stubs, run the following commands: - -``` -(.venv3)$ black stdlib stubs -(.venv3)$ isort stdlib stubs -(.venv3)$ flake8 -``` - ## Submitting Changes