VimPlug/typeshed
1
0
Fork 0
mirror of https://github.com/davidhalter/typeshed.git synced 2025-12-10 14:01:55 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

CONTRIBUTING: improve docs on running tests locally (#7992)

Browse Source 
Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
This commit is contained in:
Alex Waygood
2022-05-30 23:44:13 +01:00
committed by GitHub
parent 17e7cc7d3c
commit fa85367fc9
1 changed files with 51 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files

102
CONTRIBUTING.md
View File

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