From b82379aa9e54f24141d21ff3d572dd73a70b4267 Mon Sep 17 00:00:00 2001 From: Sebastian Rittau Date: Wed, 12 May 2021 23:06:38 +0200 Subject: [PATCH 01/20] Reshuffle sections between README and CONTRIBUTIONS Remove redundant sentences Remove extensive explanation of version checks --- CONTRIBUTING.md | 182 ++++++++++++++++++++++++++---------------------- README.md | 111 +++++++++-------------------- 2 files changed, 131 insertions(+), 162 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c81c0d4db5df..c6867d1370f9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -28,24 +28,7 @@ are important to the project's success. For more details, read below. -## Discussion - -If you've run into behavior in the type checker that suggests the type -stubs for a given library are incorrect or incomplete, -we want to hear from you! - -Our main forum for discussion is the project's [GitHub issue -tracker](https://github.com/python/typeshed/issues). This is the right -place to start a discussion of any of the above or most any other -topic concerning the project. - -For less formal discussion, try the typing chat room on -[gitter.im](https://gitter.im/python/typing). Some Mypy core developers -are almost always present; feel free to find us there and we're happy -to chat. Substantive technical discussion will be directed to the -issue tracker. - -### Code of Conduct +## Code of Conduct Everyone participating in the typeshed community, and in particular in our issue tracker, pull requests, and IRC channel, is expected to treat @@ -101,6 +84,20 @@ maintainers. This ensures high quality contributions and keeps everybody on the same page. Avoid direct pushes to the repository. +## Format + +Each Python module is represented by a `.pyi` "stub file". This is a +syntactically valid Python file, although it usually cannot be run by +Python 3 (since forward references don't require string quotes). All +the methods are empty. + +Python function annotations ([PEP 3107](https://www.python.org/dev/peps/pep-3107/)) +are used to describe the signature of each function or method. + +See [PEP 484](http://www.python.org/dev/peps/pep-0484/) for the exact +syntax of the stub files and [CONTRIBUTING.md](CONTRIBUTING.md) for the +coding style used in typeshed. + ## Preparing Changes ### Before you begin @@ -181,9 +178,87 @@ point for your stubs. Note that this generator is currently unable to determine most argument and return types and omits them or uses ``Any`` in their place. Fill out manually the types that you know. -### Stub file coding style +## Standard library stubs + +The `stdlib` directory contains stubs for modules in the +Python standard library -- which +includes pure Python modules, dynamically loaded extension modules, +hard-linked extension modules, and the builtins. The `VERSIONS` file lists +the versions of Python where the module is available. + +The structure of the `VERSIONS` file is as follows: +- Blank lines and lines starting with `#` are ignored. +- Lines contain the name of a top-level module, followed by a colon, + a space, and a version range (for example: `symbol: 2.7-3.9`). + +Version ranges may be of the form "X.Y-A.B" or "X.Y-". The +first form means that a module was introduced in version X.Y and last +available in version A.B. The second form means that the module was +introduced in version X.Y and is still available in the latest +version of Python. + +Python versions before 2.7 are ignored, so any module that was already +present in 2.7 will have "2.7" as its minimum version. Version ranges +for unsupported versions of Python 3 (currently 3.5 and lower) are +generally accurate but we do not guarantee their correctness. + +The `stdlib/@python2` subdirectory contains Python 2-only stubs, +both for modules that must be kept different for Python 2 and 3, like +`builtins.pyi`, and for modules that only existed in Python 2, like +`ConfigParser.pyi`. The latter group of modules are not listed in +`VERSIONS`. + +Note that if a package is present in `@python2`, any stub in the main +`stdlib` directory should be ignored when looking for Python 2 stubs. For +example, typeshed contains files `stdlib/@python2/collections.pyi` and +`stdlib/collections/abc.pyi`. A client looking for stubs for +`collections.abc` in Python 2 should not pick up the latter file, but +instead report that the module does not exist. + +## Third-party library stubs + +Modules that are not shipped with Python but have a type description in Python +go into `stubs`. Each subdirectory there represents a PyPI distribution, and +contains the following: +* `METADATA.toml` that specifies oldest version of the source library for + which the stubs are applicable, supported Python versions (Python 3 defaults + to `True`, Python 2 defaults to `False`), and dependency on other type stub + packages. +* Stubs (i.e. `*.pyi` files) for packages and modules that are shipped in the + source distribution. Similar to standard library, if the Python 2 version of + the stubs must be kept *separate*, it can be put in a `@python` subdirectory. +* (Rarely) some docs specific to a given type stub package in `README` file. + +When a third party stub is +modified, an updated version of the corresponding distribution will be +automatically uploaded to PyPI within a few hours. +Each time this happens the least significant +version level is incremented. For example, if `stubs/foo/METADATA.toml` has +`version = "x.y"` the package on PyPI will be updated from `types-foo-x.y.n` +to `types-foo-x.y.n+1`. + +*Note:* In its current implementation, typeshed cannot contain stubs for +multiple versions of the same third-party library. Prefer to generate +stubs for the latest version released on PyPI at the time of your +stubbing. The oldest version of the library for which the stubs are still +applicable (i.e. reflect the actual runtime behaviour) can be indicated +in `METADATA.toml` as `version = "x.y"`. Note that only two most significant +version levels are supported (i.e. only single dot). When a significant change +is made in the library, the version of the stub should be bumped (note that +previous versions are still available on PyPI). + +### Removal policy + +Third-party packages are generally removed from typeshed when one of the +following criteria is met: + +* The upstream package ships a py.typed file for at least 6-12 months, or +* the package does not support any of the Python versions supported by + typeshed. -#### Syntax example +## Stub file coding style + +### Syntax example The below is an excerpt from the types for the `datetime` module. @@ -206,7 +281,7 @@ class date: def weekday(self) -> int: ... ``` -#### Conventions +### Conventions Stub files are *like* Python files and you should generally expect them to look the same. Your tools should be able to successfully treat them @@ -308,62 +383,20 @@ contributors. ### Stub versioning -There are separate directories for `stdlib` (standard library) and `stubs` -(all other stubs). For standard library stubs Python version support is -given in `VERSIONS` file. Each line in this file is a module or package name -followed by `: `, followed by the oldest *supported* Python version where -the module is available. - -Third-party stubs only support Python 3 by default. You can optionally supply -Python 2 stubs for a package by placing them into a `@python2` subdirectory -for the corresponding distribution. Some older stubs also indicate Python 2 -support by setting `python2 = True` in the corresponding `METADATA.toml` file. - You can use checks like `if sys.version_info >= (3, 8):` to denote new functionality introduced in a given Python version or solve type differences. When doing so, only use -one-tuples or two-tuples. This is because: - -* mypy doesn't support more fine-grained version checks; and more - importantly - -* the micro versions of a Python release will change over time in your - checking environment and the checker should return consistent results - regardless of the micro version used. - -Because of this, if a given functionality was introduced in, say, Python -3.7.4, your check: +one-tuples or two-tuples. Because of this, if a given functionality was +introduced in, say, Python 3.7.4, your check: * should be expressed as `if sys.version_info >= (3, 7):` * should NOT be expressed as `if sys.version_info >= (3, 7, 4):` * should NOT be expressed as `if sys.version_info >= (3, 8):` -This makes the type checker assume the functionality was also available -in 3.7.0 - 3.7.3, which while *technically* incorrect is relatively -harmless. This is a strictly better compromise than using the latter -two forms, which would generate false positive errors for correct use -under Python 3.7.4. - When your stub contains if statements for different Python versions, always put the code for the most recent Python version first. -Note: in its current implementation, typeshed cannot contain stubs for -multiple versions of the same third-party library. Prefer to generate -stubs for the latest version released on PyPI at the time of your -stubbing. The oldest version of the library for which the stubs are still -applicable (i.e. reflect the actual runtime behaviour) can be indicated -in `METADATA.toml` as `version = "x.y"`. Note that only two most significant -version levels are supported (i.e. only single dot). When a significant change -is made in the library, the version of the stub should be bumped (note that -previous versions are still available on PyPI). - -Internal typeshed machinery will periodically build and upload modified -third party packages to PyPI, each time this happens the least significant -version level is incremented. For example, if `stubs/foo/METADATA.toml` has -`version = "x.y"` the package on PyPI will be updated from `types-foo-x.y.n` -to `types-foo-x.y.n+1`. - -### What to do when a project's documentation and implementation disagree +## What to do when a project's documentation and implementation disagree Type stubs are meant to be external type annotations for a given library. While they are useful documentation in its own merit, they @@ -372,22 +405,7 @@ documentation. Whenever you find them disagreeing, model the type information after the actual implementation and file an issue on the project's tracker to fix their documentation. -## Issue-tracker conventions - -We aim to reply to all new issues promptly. We'll assign one or more -labels to indicate we've triaged an issue, but most typeshed issues -are relatively simple (stubs for a given module or package are -missing, incomplete or incorrect) and we won't add noise to the -tracker by labeling all of them. Please see the -[list of all labels](https://github.com/python/typeshed/issues/labels) -for a detailed description of the labels we use. - -Sometimes a PR can't make progress until some external issue is -addressed. We indicate this by editing the subject to add a ``[WIP]`` -prefix. (This should be removed before committing the issue once -unblocked!) - -### Maintainer guidelines +## Maintainer guidelines Maintainers should follow these rules when processing pull requests: diff --git a/README.md b/README.md index d0f2279ec014..6760b5412d25 100644 --- a/README.md +++ b/README.md @@ -38,86 +38,37 @@ type stub packages (if found on PyPI). PyCharm, pytype etc. work in a similar way, for more details see documentation for the type-checking tool you are using. -## Format - -Each Python module is represented by a `.pyi` "stub file". This is a -syntactically valid Python file, although it usually cannot be run by -Python 3 (since forward references don't require string quotes). All -the methods are empty. - -Python function annotations ([PEP 3107](https://www.python.org/dev/peps/pep-3107/)) -are used to describe the signature of each function or method. - -See [PEP 484](http://www.python.org/dev/peps/pep-0484/) for the exact -syntax of the stub files and [CONTRIBUTING.md](CONTRIBUTING.md) for the -coding style used in typeshed. - -## Directory structure - -### stdlib - -This contains stubs for modules in the Python standard library -- which -includes pure Python modules, dynamically loaded extension modules, -hard-linked extension modules, and the builtins. The `VERSIONS` file lists -the versions of Python where the module is available. - -The structure of the `VERSIONS` file is as follows: -- Blank lines and lines starting with `#` are ignored. -- Lines contain the name of a top-level module, followed by a colon, - a space, and a version range (for example: `symbol: 2.7-3.9`). - -Version ranges may be of the form "X.Y-A.B" or "X.Y-". The -first form means that a module was introduced in version X.Y and last -available in version A.B. The second form means that the module was -introduced in version X.Y and is still available in the latest -version of Python. - -Python versions before 2.7 are ignored, so any module that was already -present in 2.7 will have "2.7" as its minimum version. Version ranges -for unsupported versions of Python 3 (currently 3.5 and lower) are -generally accurate but we do not guarantee their correctness. - -The `stdlib/@python2` subdirectory contains Python 2-only stubs, -both for modules that must be kept different for Python 2 and 3, like -`builtins.pyi`, and for modules that only existed in Python 2, like -`ConfigParser.pyi`. The latter group of modules are not listed in -`VERSIONS`. - -Note that if a package is present in `@python2`, any stub in the main -`stdlib` directory should be ignored when looking for Python 2 stubs. For -example, typeshed contains files `stdlib/@python2/collections.pyi` and -`stdlib/collections/abc.pyi`. A client looking for stubs for -`collections.abc` in Python 2 should not pick up the latter file, but -instead report that the module does not exist. - -### stubs - -Modules that are not shipped with Python but have a type description in Python -go into `stubs`. Each subdirectory there represents a PyPI distribution, and -contains the following: -* `METADATA.toml` that specifies oldest version of the source library for - which the stubs are applicable, supported Python versions (Python 3 defaults - to `True`, Python 2 defaults to `False`), and dependency on other type stub - packages. -* Stubs (i.e. `*.pyi` files) for packages and modules that are shipped in the - source distribution. Similar to standard library, if the Python 2 version of - the stubs must be kept *separate*, it can be put in a `@python` subdirectory. -* (Rarely) some docs specific to a given type stub package in `README` file. - -No other files are allowed in `stdlib` and `stubs`. When a third party stub is -modified, an updated version of the corresponding distribution will be -automatically uploaded to PyPI shortly (within few hours). - -For more information on directory structure and stub versioning, see -[the relevant section of CONTRIBUTING.md]( -https://github.com/python/typeshed/blob/master/CONTRIBUTING.md#stub-versioning). - -Third-party packages are generally removed from typeshed when one of the -following criteria is met: - -* The upstream package ships a py.typed file for at least 6-12 months, or -* the package does not support any of the Python versions supported by - typeshed. +## Discussion + +If you've run into behavior in the type checker that suggests the type +stubs for a given library are incorrect or incomplete, +we want to hear from you! + +Our main forum for discussion is the project's [GitHub issue +tracker](https://github.com/python/typeshed/issues). This is the right +place to start a discussion of any of the above or most any other +topic concerning the project. + +For less formal discussion, try the typing chat room on +[gitter.im](https://gitter.im/python/typing). Some Mypy core developers +are almost always present; feel free to find us there and we're happy +to chat. Substantive technical discussion will be directed to the +issue tracker. + +## Issue-tracker conventions + +We aim to reply to all new issues promptly. We'll assign one or more +labels to indicate we've triaged an issue, but most typeshed issues +are relatively simple (stubs for a given module or package are +missing, incomplete or incorrect) and we won't add noise to the +tracker by labeling all of them. Please see the +[list of all labels](https://github.com/python/typeshed/issues/labels) +for a detailed description of the labels we use. + +Sometimes a PR can't make progress until some external issue is +addressed. We indicate this by editing the subject to add a ``[WIP]`` +prefix. (This should be removed before committing the issue once +unblocked!) ## Contributing From 00e9395ce548aac9e6233ba88ca7d2fabaf233db Mon Sep 17 00:00:00 2001 From: Sebastian Rittau Date: Wed, 12 May 2021 23:10:07 +0200 Subject: [PATCH 02/20] Remove Contributing section (duplicated information) --- README.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/README.md b/README.md index 6760b5412d25..75d3c4e976ab 100644 --- a/README.md +++ b/README.md @@ -70,11 +70,6 @@ addressed. We indicate this by editing the subject to add a ``[WIP]`` prefix. (This should be removed before committing the issue once unblocked!) -## Contributing - -Please read [CONTRIBUTING.md](CONTRIBUTING.md) before submitting pull requests. -If you have questions related to contributing, drop by the [typing Gitter](https://gitter.im/python/typing). - ## Running the tests The tests are automatically run on every PR and push to the repo. From e8be47b2eb99f9b3917c92d5626b8463cbc2fe6c Mon Sep 17 00:00:00 2001 From: Sebastian Rittau Date: Wed, 12 May 2021 23:11:25 +0200 Subject: [PATCH 03/20] Move Running the tests to CONTRIBUTING --- CONTRIBUTING.md | 134 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 134 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c6867d1370f9..b2af65d9b5f2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -405,6 +405,140 @@ documentation. Whenever you find them disagreeing, model the type information after the actual implementation and file an issue on the project's tracker to fix their documentation. +## Running the tests + +The tests are automatically run on every PR and push to the repo. +Therefore you don't need to run them locally, unless you want to run +them before making a pull request or you want to debug some problem without +creating several small commits. + +There are several tests: +- `tests/mypy_test.py` +tests typeshed with [mypy](https://github.com/python/mypy/) +- `tests/pytype_test.py` tests typeshed with +[pytype](https://github.com/google/pytype/). +- `tests/pyright_test.py` tests typeshed with +[pyright](https://github.com/microsoft/pyright). +- `tests/mypy_test_suite.py` runs a subset of mypy's test suite using this version of +typeshed. +- `tests/check_consistent.py` checks certain files in typeshed remain +consistent with each other. +- `tests/stubtest_test.py` checks stubs against the objects at runtime. +- `flake8` enforces a style guide. + +### Setup + +Run: +``` +$ python3 -m venv .venv3 +$ source .venv3/bin/activate +(.venv3)$ pip install -U pip +(.venv3)$ pip install -r requirements-tests-py3.txt +``` +This will install mypy (you need the latest master branch from GitHub), +typed-ast, flake8 (and plugins), pytype, black and isort. + +If you want to run the pyright tests, you need to have +[Node.js](https://nodejs.org/) installed. + +### mypy_test.py + +This test requires Python 3.6 or higher; Python 3.6.1 or higher is recommended. +Run using: +``` +(.venv3)$ python3 tests/mypy_test.py +``` + +This test is shallow — it verifies that all stubs can be +imported but doesn't check whether stubs match their implementation +(in the Python standard library or a third-party package). It has an exclude list of +modules that are not tested at all, which also lives in the tests directory. + +You can restrict mypy tests to a single version by passing `-p2` or `-p3.9`: +```bash +(.venv3)$ python3 tests/mypy_test.py -p3.9 +``` + +### pytype_test.py + +This test requires Python 2.7 and Python 3.6. Pytype will +find these automatically if they're in `PATH`, but otherwise you must point to +them with the `--python27-exe` and `--python36-exe` arguments, respectively. +Run using: +``` +(.venv3)$ python3 tests/pytype_test.py +``` + +This test works similarly to `mypy_test.py`, except it uses `pytype`. + +### pyright\_test.py + +This test requires Node.js to be installed. It is currently not part of the CI, +but it uses the same pyright version and configuration as the CI. +``` +(.venv3)$ python3 tests/pyright_test.py # Check all files +(.venv3)$ python3 tests/pyright_test.py stdlib/sys.pyi # Check one file +``` + +### mypy\_test\_suite.py + +This test requires Python 3.5 or higher; Python 3.6.1 or higher is recommended. +Run using: +``` +(.venv3)$ python3 tests/mypy_test_suite.py +``` + +This test runs mypy's own test suite using the typeshed code in your repo. This +will sometimes catch issues with incorrectly typed stubs, but is much slower +than the other tests. + +### check_consistent.py + +Run using: +``` +python3 tests/check_consistent.py +``` + +### stubtest_test.py + +This test requires Python 3.6 or higher. +Run using +``` +(.venv3)$ python3 tests/stubtest_test.py +``` + +This test compares the stdlib stubs against the objects at runtime. Because of +this, the output depends on which version of Python and on what kind of system +it is run. +Thus the easiest way to run this test is via Github Actions on your fork; +if you run it locally, it'll likely complain about system-specific +differences (in e.g, `socket`) that the type system cannot capture. +If you need a specific version of Python to repro a CI failure, +[pyenv](https://github.com/pyenv/pyenv) can help. + +Due to its dynamic nature, you may run into false positives. In this case, you +can add to the whitelists for each affected Python version in +`tests/stubtest_whitelists`. Please file issues for stubtest false positives +at [mypy](https://github.com/python/mypy/issues). + +To run stubtest against third party stubs, it's easiest to use stubtest +directly, with +``` +(.venv3)$ python3 -m mypy.stubtest \ + --custom-typeshed-dir \ + +``` +stubtest can also help you find things missing from the stubs. + + +### flake8 + +flake8 requires Python 3.6 or higher. Run using: +``` +(.venv3)$ flake8 +``` + +Note typeshed uses the `flake8-pyi` and `flake8-bugbear` plugins. ## Maintainer guidelines Maintainers should follow these rules when processing pull requests: From 460701f435579648d3936427560e3e2f822b8ca0 Mon Sep 17 00:00:00 2001 From: Sebastian Rittau Date: Wed, 12 May 2021 23:12:05 +0200 Subject: [PATCH 04/20] Move Running the tests to CONTRIBUTING --- README.md | 134 ------------------------------------------------------ 1 file changed, 134 deletions(-) diff --git a/README.md b/README.md index 75d3c4e976ab..2257a037cdba 100644 --- a/README.md +++ b/README.md @@ -70,137 +70,3 @@ addressed. We indicate this by editing the subject to add a ``[WIP]`` prefix. (This should be removed before committing the issue once unblocked!) -## Running the tests - -The tests are automatically run on every PR and push to the repo. -Therefore you don't need to run them locally, unless you want to run -them before making a pull request or you want to debug some problem without -creating several small commits. - -There are several tests: -- `tests/mypy_test.py` -tests typeshed with [mypy](https://github.com/python/mypy/) -- `tests/pytype_test.py` tests typeshed with -[pytype](https://github.com/google/pytype/). -- `tests/pyright_test.py` tests typeshed with -[pyright](https://github.com/microsoft/pyright). -- `tests/mypy_test_suite.py` runs a subset of mypy's test suite using this version of -typeshed. -- `tests/check_consistent.py` checks certain files in typeshed remain -consistent with each other. -- `tests/stubtest_test.py` checks stubs against the objects at runtime. -- `flake8` enforces a style guide. - -### Setup - -Run: -``` -$ python3 -m venv .venv3 -$ source .venv3/bin/activate -(.venv3)$ pip install -U pip -(.venv3)$ pip install -r requirements-tests-py3.txt -``` -This will install mypy (you need the latest master branch from GitHub), -typed-ast, flake8 (and plugins), pytype, black and isort. - -If you want to run the pyright tests, you need to have -[Node.js](https://nodejs.org/) installed. - -### mypy_test.py - -This test requires Python 3.6 or higher; Python 3.6.1 or higher is recommended. -Run using: -``` -(.venv3)$ python3 tests/mypy_test.py -``` - -This test is shallow — it verifies that all stubs can be -imported but doesn't check whether stubs match their implementation -(in the Python standard library or a third-party package). It has an exclude list of -modules that are not tested at all, which also lives in the tests directory. - -You can restrict mypy tests to a single version by passing `-p2` or `-p3.9`: -```bash -(.venv3)$ python3 tests/mypy_test.py -p3.9 -``` - -### pytype_test.py - -This test requires Python 2.7 and Python 3.6. Pytype will -find these automatically if they're in `PATH`, but otherwise you must point to -them with the `--python27-exe` and `--python36-exe` arguments, respectively. -Run using: -``` -(.venv3)$ python3 tests/pytype_test.py -``` - -This test works similarly to `mypy_test.py`, except it uses `pytype`. - -### pyright\_test.py - -This test requires Node.js to be installed. It is currently not part of the CI, -but it uses the same pyright version and configuration as the CI. -``` -(.venv3)$ python3 tests/pyright_test.py # Check all files -(.venv3)$ python3 tests/pyright_test.py stdlib/sys.pyi # Check one file -``` - -### mypy\_test\_suite.py - -This test requires Python 3.5 or higher; Python 3.6.1 or higher is recommended. -Run using: -``` -(.venv3)$ python3 tests/mypy_test_suite.py -``` - -This test runs mypy's own test suite using the typeshed code in your repo. This -will sometimes catch issues with incorrectly typed stubs, but is much slower -than the other tests. - -### check_consistent.py - -Run using: -``` -python3 tests/check_consistent.py -``` - -### stubtest_test.py - -This test requires Python 3.6 or higher. -Run using -``` -(.venv3)$ python3 tests/stubtest_test.py -``` - -This test compares the stdlib stubs against the objects at runtime. Because of -this, the output depends on which version of Python and on what kind of system -it is run. -Thus the easiest way to run this test is via Github Actions on your fork; -if you run it locally, it'll likely complain about system-specific -differences (in e.g, `socket`) that the type system cannot capture. -If you need a specific version of Python to repro a CI failure, -[pyenv](https://github.com/pyenv/pyenv) can help. - -Due to its dynamic nature, you may run into false positives. In this case, you -can add to the whitelists for each affected Python version in -`tests/stubtest_whitelists`. Please file issues for stubtest false positives -at [mypy](https://github.com/python/mypy/issues). - -To run stubtest against third party stubs, it's easiest to use stubtest -directly, with -``` -(.venv3)$ python3 -m mypy.stubtest \ - --custom-typeshed-dir \ - -``` -stubtest can also help you find things missing from the stubs. - - -### flake8 - -flake8 requires Python 3.6 or higher. Run using: -``` -(.venv3)$ flake8 -``` - -Note typeshed uses the `flake8-pyi` and `flake8-bugbear` plugins. From dc4b43b9009f5c810bda8cf1fbe153c83a35bbcc Mon Sep 17 00:00:00 2001 From: Sebastian Rittau Date: Wed, 12 May 2021 23:14:00 +0200 Subject: [PATCH 05/20] Read 'this document', not README --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b2af65d9b5f2..ce51baf792f6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,7 +8,7 @@ are important to the project's success. ## The contribution process at a glance -1. Read the [README.md file](README.md). +1. Read this document. 2. If you want, set up your environment to be able to [run tests](README.md#running-the-tests). This can be useful for big pull requests or fixing specific errors, but usually is not needed, because the tests run automatically on GitHub Actions From 68f8c56106b5fe65eecfa0e44476b2bb18a4dc35 Mon Sep 17 00:00:00 2001 From: Sebastian Rittau Date: Wed, 12 May 2021 23:15:05 +0200 Subject: [PATCH 06/20] Linkfix --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ce51baf792f6..ba21beade02e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,7 +9,7 @@ are important to the project's success. ## The contribution process at a glance 1. Read this document. -2. If you want, set up your environment to be able to [run tests](README.md#running-the-tests). +2. If you want, set up your environment to be able to [run tests](#running-the-tests). This can be useful for big pull requests or fixing specific errors, but usually is not needed, because the tests run automatically on GitHub Actions for all pull requests. From 41bc67ae4110b6846ecf1517adfa9efe6de2c225 Mon Sep 17 00:00:00 2001 From: Sebastian Rittau Date: Wed, 12 May 2021 23:16:51 +0200 Subject: [PATCH 07/20] Linkfix --- CONTRIBUTING.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ba21beade02e..d45366e70582 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,16 +9,16 @@ are important to the project's success. ## The contribution process at a glance 1. Read this document. -2. If you want, set up your environment to be able to [run tests](#running-the-tests). - This can be useful for big pull requests or fixing specific errors, but - usually is not needed, because the tests run automatically on GitHub Actions - for all pull requests. -3. [Prepare your changes](#preparing-changes): +2. [Prepare your changes](#preparing-changes): * Small fixes and additions can be submitted directly as pull requests, - but [contact us](#discussion) before starting significant work. + but [contact us](README.md#discussion) before starting significant work. * Create your stubs [conforming to the coding style](#stub-file-coding-style). * Make sure your tests pass cleanly on `mypy`, `pytype`, and `flake8`. * Reformat your stubs with `black` and `isort`. +3. If you want, set up your environment to be able to [run tests](#running-the-tests). + This can be useful for big pull requests or fixing specific errors, but + usually is not needed, because the tests run automatically on GitHub Actions + for all pull requests. 4. [Submit your changes](#submitting-changes) by opening a pull request. 5. You can expect a reply within a few days: * Diffs are merged when considered ready by the core team. From fd7e1cba0a34a9e406da62fd1a426d94ca6cca07 Mon Sep 17 00:00:00 2001 From: Sebastian Rittau Date: Wed, 12 May 2021 23:18:07 +0200 Subject: [PATCH 08/20] Remove 'read this document' --- CONTRIBUTING.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d45366e70582..8f51fd1fca2a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,19 +8,18 @@ are important to the project's success. ## The contribution process at a glance -1. Read this document. -2. [Prepare your changes](#preparing-changes): +1. [Prepare your changes](#preparing-changes): * Small fixes and additions can be submitted directly as pull requests, but [contact us](README.md#discussion) before starting significant work. * Create your stubs [conforming to the coding style](#stub-file-coding-style). * Make sure your tests pass cleanly on `mypy`, `pytype`, and `flake8`. * Reformat your stubs with `black` and `isort`. -3. If you want, set up your environment to be able to [run tests](#running-the-tests). +2. If you want, set up your environment to be able to [run tests](#running-the-tests). This can be useful for big pull requests or fixing specific errors, but usually is not needed, because the tests run automatically on GitHub Actions for all pull requests. -4. [Submit your changes](#submitting-changes) by opening a pull request. -5. You can expect a reply within a few days: +3. [Submit your changes](#submitting-changes) by opening a pull request. +4. You can expect a reply within a few days: * Diffs are merged when considered ready by the core team. * Feel free to ping the core team if your pull request goes without a reply for more than a few days. From f9861aedee7f230c82e37a9f717e30c3c446a417 Mon Sep 17 00:00:00 2001 From: Sebastian Rittau Date: Wed, 12 May 2021 23:20:28 +0200 Subject: [PATCH 09/20] Move Code of Conduct to README --- CONTRIBUTING.md | 9 --------- README.md | 7 +++++++ 2 files changed, 7 insertions(+), 9 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8f51fd1fca2a..e22424cd125c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -27,15 +27,6 @@ are important to the project's success. For more details, read below. -## Code of Conduct - -Everyone participating in the typeshed community, and in particular in -our issue tracker, pull requests, and IRC channel, is expected to treat -other people with respect and more generally to follow the guidelines -articulated in the [Python Community Code of -Conduct](https://www.python.org/psf/codeofconduct/). - - ## Submitting Changes Even more excellent than a good bug report is a fix for a bug, or the diff --git a/README.md b/README.md index 2257a037cdba..0eef079fe233 100644 --- a/README.md +++ b/README.md @@ -70,3 +70,10 @@ addressed. We indicate this by editing the subject to add a ``[WIP]`` prefix. (This should be removed before committing the issue once unblocked!) +## Code of Conduct + +Everyone participating in the typeshed community, and in particular in +our issue tracker, pull requests, and IRC channel, is expected to treat +other people with respect and more generally to follow the guidelines +articulated in the [Python Community Code of +Conduct](https://www.python.org/psf/codeofconduct/). From af3275672e5ac40ce5dbe2c41f920458da7d81cb Mon Sep 17 00:00:00 2001 From: Sebastian Rittau Date: Wed, 12 May 2021 23:37:35 +0200 Subject: [PATCH 10/20] Reorder CONTRIBUTING to follow process --- CONTRIBUTING.md | 323 ++++++++++++++++++++++++------------------------ 1 file changed, 163 insertions(+), 160 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e22424cd125c..46b520cc9adf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,18 +8,19 @@ are important to the project's success. ## The contribution process at a glance -1. [Prepare your changes](#preparing-changes): +1. Find out [where to make your changes](#where-to-make-changes). +2. [Prepare your changes](#preparing-changes): * Small fixes and additions can be submitted directly as pull requests, but [contact us](README.md#discussion) before starting significant work. - * Create your stubs [conforming to the coding style](#stub-file-coding-style). - * Make sure your tests pass cleanly on `mypy`, `pytype`, and `flake8`. + * Create your stubs, considering [what to include](#what-to-include) and + conforming to the [coding style](#stub-file-coding-style). * Reformat your stubs with `black` and `isort`. -2. If you want, set up your environment to be able to [run tests](#running-the-tests). +3. If you want, set up your environment to be able to [run tests](#running-the-tests). This can be useful for big pull requests or fixing specific errors, but usually is not needed, because the tests run automatically on GitHub Actions for all pull requests. -3. [Submit your changes](#submitting-changes) by opening a pull request. -4. You can expect a reply within a few days: +4. [Submit your changes](#submitting-changes) by opening a pull request. +5. You can expect a reply within a few days: * Diffs are merged when considered ready by the core team. * Feel free to ping the core team if your pull request goes without a reply for more than a few days. @@ -27,54 +28,87 @@ are important to the project's success. For more details, read below. -## Submitting Changes +## Where to make changes -Even more excellent than a good bug report is a fix for a bug, or the -implementation of a much-needed stub. We'd love to have -your contributions. +### Standard library stubs -We use the usual GitHub pull-request flow, which may be familiar to -you if you've contributed to other projects on GitHub. For the -mechanics, see [Mypy's git and GitHub workflow help page](https://github.com/python/mypy/wiki/Using-Git-And-GitHub), -or [GitHub's own documentation](https://help.github.com/articles/using-pull-requests/). +The `stdlib` directory contains stubs for modules in the +Python standard library -- which +includes pure Python modules, dynamically loaded extension modules, +hard-linked extension modules, and the builtins. The `VERSIONS` file lists +the versions of Python where the module is available. -Anyone interested in type stubs may review your code. One of the -maintainers will merge your pull request when they think it's ready. -For every pull request, we aim to promptly either merge it or say why -it's not yet ready; if you go a few days without a reply, please feel -free to ping the thread by adding a new comment. +The structure of the `VERSIONS` file is as follows: +- Blank lines and lines starting with `#` are ignored. +- Lines contain the name of a top-level module, followed by a colon, + a space, and a version range (for example: `symbol: 2.7-3.9`). -To get your pull request merged sooner, you should explain why you are -making the change. For example, you can point to a code sample that is -processed incorrectly by a type checker. It is also helpful to add -links to online documentation or to the implementation of the code -you are changing. +Version ranges may be of the form "X.Y-A.B" or "X.Y-". The +first form means that a module was introduced in version X.Y and last +available in version A.B. The second form means that the module was +introduced in version X.Y and is still available in the latest +version of Python. -Also, do not squash your commits or use `git commit --amend` after you have submitted a pull request, as this -erases context during review. We will squash commits when the pull request is merged. -This way, your pull request will appear as a single commit in our git history, even -if it consisted of several smaller commits. +Python versions before 2.7 are ignored, so any module that was already +present in 2.7 will have "2.7" as its minimum version. Version ranges +for unsupported versions of Python 3 (currently 3.5 and lower) are +generally accurate but we do not guarantee their correctness. -At present the maintainers are (alphabetically): -* David Fisher (@ddfisher) -* Łukasz Langa (@ambv) -* Jukka Lehtosalo (@JukkaL) -* Ivan Levkivskyi (@ilevkivskyi) -* Matthias Kramm (@matthiaskramm) -* Greg Price (@gnprice) -* Sebastian Rittau (@srittau) -* Guido van Rossum (@gvanrossum) -* Shantanu (@hauntsaninja) -* Rune Tynan (@CraftSpider) -* Aku Viljanen (@Akuli) -* Jelle Zijlstra (@JelleZijlstra) +The `stdlib/@python2` subdirectory contains Python 2-only stubs, +both for modules that must be kept different for Python 2 and 3, like +`builtins.pyi`, and for modules that only existed in Python 2, like +`ConfigParser.pyi`. The latter group of modules are not listed in +`VERSIONS`. -NOTE: the process for preparing and submitting changes also applies to -maintainers. This ensures high quality contributions and keeps -everybody on the same page. Avoid direct pushes to the repository. +Note that if a package is present in `@python2`, any stub in the main +`stdlib` directory should be ignored when looking for Python 2 stubs. For +example, typeshed contains files `stdlib/@python2/collections.pyi` and +`stdlib/collections/abc.pyi`. A client looking for stubs for +`collections.abc` in Python 2 should not pick up the latter file, but +instead report that the module does not exist. + +### Third-party library stubs + +Modules that are not shipped with Python but have a type description in Python +go into `stubs`. Each subdirectory there represents a PyPI distribution, and +contains the following: +* `METADATA.toml` that specifies oldest version of the source library for + which the stubs are applicable, supported Python versions (Python 3 defaults + to `True`, Python 2 defaults to `False`), and dependency on other type stub + packages. +* Stubs (i.e. `*.pyi` files) for packages and modules that are shipped in the + source distribution. Similar to standard library, if the Python 2 version of + the stubs must be kept *separate*, it can be put in a `@python` subdirectory. +* (Rarely) some docs specific to a given type stub package in `README` file. +When a third party stub is +modified, an updated version of the corresponding distribution will be +automatically uploaded to PyPI within a few hours. +Each time this happens the least significant +version level is incremented. For example, if `stubs/foo/METADATA.toml` has +`version = "x.y"` the package on PyPI will be updated from `types-foo-x.y.n` +to `types-foo-x.y.n+1`. -## Format +*Note:* In its current implementation, typeshed cannot contain stubs for +multiple versions of the same third-party library. Prefer to generate +stubs for the latest version released on PyPI at the time of your +stubbing. The oldest version of the library for which the stubs are still +applicable (i.e. reflect the actual runtime behaviour) can be indicated +in `METADATA.toml` as `version = "x.y"`. Note that only two most significant +version levels are supported (i.e. only single dot). When a significant change +is made in the library, the version of the stub should be bumped (note that +previous versions are still available on PyPI). + +## Preparing Changes + +### Before you begin + +If your change will be a significant amount of work to write, we highly +recommend starting by opening an issue laying out what you want to do. +That lets a conversation happen early in case other contributors disagree +with what you'd like to do or have ideas that will help you do it. + +### Format Each Python module is represented by a `.pyi` "stub file". This is a syntactically valid Python file, although it usually cannot be run by @@ -88,15 +122,6 @@ See [PEP 484](http://www.python.org/dev/peps/pep-0484/) for the exact syntax of the stub files and [CONTRIBUTING.md](CONTRIBUTING.md) for the coding style used in typeshed. -## Preparing Changes - -### Before you begin - -If your change will be a significant amount of work to write, we highly -recommend starting by opening an issue laying out what you want to do. -That lets a conversation happen early in case other contributors disagree -with what you'd like to do or have ideas that will help you do it. - ### What to include Stubs should include the complete interface (classes, functions, @@ -127,6 +152,30 @@ negatives (no errors for wrong code) over false positives (type errors for correct code). In addition, even for private objects a type checker can be helpful in pointing out that an incorrect type was used. +### What to do when a project's documentation and implementation disagree + +Type stubs are meant to be external type annotations for a given +library. While they are useful documentation in its own merit, they +augment the project's concrete implementation, not the project's +documentation. Whenever you find them disagreeing, model the type +information after the actual implementation and file an issue on the +project's tracker to fix their documentation. + +### Stub versioning + +You can use checks +like `if sys.version_info >= (3, 8):` to denote new functionality introduced +in a given Python version or solve type differences. When doing so, only use +one-tuples or two-tuples. Because of this, if a given functionality was +introduced in, say, Python 3.7.4, your check: + +* should be expressed as `if sys.version_info >= (3, 7):` +* should NOT be expressed as `if sys.version_info >= (3, 7, 4):` +* should NOT be expressed as `if sys.version_info >= (3, 8):` + +When your stub contains if statements for different Python versions, +always put the code for the most recent Python version first. + ### Incomplete stubs We accept partial stubs, especially for larger packages. These need to @@ -168,84 +217,6 @@ point for your stubs. Note that this generator is currently unable to determine most argument and return types and omits them or uses ``Any`` in their place. Fill out manually the types that you know. -## Standard library stubs - -The `stdlib` directory contains stubs for modules in the -Python standard library -- which -includes pure Python modules, dynamically loaded extension modules, -hard-linked extension modules, and the builtins. The `VERSIONS` file lists -the versions of Python where the module is available. - -The structure of the `VERSIONS` file is as follows: -- Blank lines and lines starting with `#` are ignored. -- Lines contain the name of a top-level module, followed by a colon, - a space, and a version range (for example: `symbol: 2.7-3.9`). - -Version ranges may be of the form "X.Y-A.B" or "X.Y-". The -first form means that a module was introduced in version X.Y and last -available in version A.B. The second form means that the module was -introduced in version X.Y and is still available in the latest -version of Python. - -Python versions before 2.7 are ignored, so any module that was already -present in 2.7 will have "2.7" as its minimum version. Version ranges -for unsupported versions of Python 3 (currently 3.5 and lower) are -generally accurate but we do not guarantee their correctness. - -The `stdlib/@python2` subdirectory contains Python 2-only stubs, -both for modules that must be kept different for Python 2 and 3, like -`builtins.pyi`, and for modules that only existed in Python 2, like -`ConfigParser.pyi`. The latter group of modules are not listed in -`VERSIONS`. - -Note that if a package is present in `@python2`, any stub in the main -`stdlib` directory should be ignored when looking for Python 2 stubs. For -example, typeshed contains files `stdlib/@python2/collections.pyi` and -`stdlib/collections/abc.pyi`. A client looking for stubs for -`collections.abc` in Python 2 should not pick up the latter file, but -instead report that the module does not exist. - -## Third-party library stubs - -Modules that are not shipped with Python but have a type description in Python -go into `stubs`. Each subdirectory there represents a PyPI distribution, and -contains the following: -* `METADATA.toml` that specifies oldest version of the source library for - which the stubs are applicable, supported Python versions (Python 3 defaults - to `True`, Python 2 defaults to `False`), and dependency on other type stub - packages. -* Stubs (i.e. `*.pyi` files) for packages and modules that are shipped in the - source distribution. Similar to standard library, if the Python 2 version of - the stubs must be kept *separate*, it can be put in a `@python` subdirectory. -* (Rarely) some docs specific to a given type stub package in `README` file. - -When a third party stub is -modified, an updated version of the corresponding distribution will be -automatically uploaded to PyPI within a few hours. -Each time this happens the least significant -version level is incremented. For example, if `stubs/foo/METADATA.toml` has -`version = "x.y"` the package on PyPI will be updated from `types-foo-x.y.n` -to `types-foo-x.y.n+1`. - -*Note:* In its current implementation, typeshed cannot contain stubs for -multiple versions of the same third-party library. Prefer to generate -stubs for the latest version released on PyPI at the time of your -stubbing. The oldest version of the library for which the stubs are still -applicable (i.e. reflect the actual runtime behaviour) can be indicated -in `METADATA.toml` as `version = "x.y"`. Note that only two most significant -version levels are supported (i.e. only single dot). When a significant change -is made in the library, the version of the stub should be bumped (note that -previous versions are still available on PyPI). - -### Removal policy - -Third-party packages are generally removed from typeshed when one of the -following criteria is met: - -* The upstream package ships a py.typed file for at least 6-12 months, or -* the package does not support any of the Python versions supported by - typeshed. - ## Stub file coding style ### Syntax example @@ -371,30 +342,6 @@ NOTE: there are stubs in this repository that don't conform to the style described above. Fixing them is a great starting point for new contributors. -### Stub versioning - -You can use checks -like `if sys.version_info >= (3, 8):` to denote new functionality introduced -in a given Python version or solve type differences. When doing so, only use -one-tuples or two-tuples. Because of this, if a given functionality was -introduced in, say, Python 3.7.4, your check: - -* should be expressed as `if sys.version_info >= (3, 7):` -* should NOT be expressed as `if sys.version_info >= (3, 7, 4):` -* should NOT be expressed as `if sys.version_info >= (3, 8):` - -When your stub contains if statements for different Python versions, -always put the code for the most recent Python version first. - -## What to do when a project's documentation and implementation disagree - -Type stubs are meant to be external type annotations for a given -library. While they are useful documentation in its own merit, they -augment the project's concrete implementation, not the project's -documentation. Whenever you find them disagreeing, model the type -information after the actual implementation and file an issue on the -project's tracker to fix their documentation. - ## Running the tests The tests are automatically run on every PR and push to the repo. @@ -431,7 +378,7 @@ typed-ast, flake8 (and plugins), pytype, black and isort. If you want to run the pyright tests, you need to have [Node.js](https://nodejs.org/) installed. -### mypy_test.py +### mypy\_test.py This test requires Python 3.6 or higher; Python 3.6.1 or higher is recommended. Run using: @@ -449,7 +396,7 @@ You can restrict mypy tests to a single version by passing `-p2` or `-p3.9`: (.venv3)$ python3 tests/mypy_test.py -p3.9 ``` -### pytype_test.py +### pytype\_test.py This test requires Python 2.7 and Python 3.6. Pytype will find these automatically if they're in `PATH`, but otherwise you must point to @@ -482,14 +429,14 @@ This test runs mypy's own test suite using the typeshed code in your repo. This will sometimes catch issues with incorrectly typed stubs, but is much slower than the other tests. -### check_consistent.py +### check\_consistent.py Run using: ``` python3 tests/check_consistent.py ``` -### stubtest_test.py +### stubtest\_test.py This test requires Python 3.6 or higher. Run using @@ -529,6 +476,62 @@ flake8 requires Python 3.6 or higher. Run using: ``` Note typeshed uses the `flake8-pyi` and `flake8-bugbear` plugins. + +## Submitting Changes + +Even more excellent than a good bug report is a fix for a bug, or the +implementation of a much-needed stub. We'd love to have +your contributions. + +We use the usual GitHub pull-request flow, which may be familiar to +you if you've contributed to other projects on GitHub. For the +mechanics, see [Mypy's git and GitHub workflow help page](https://github.com/python/mypy/wiki/Using-Git-And-GitHub), +or [GitHub's own documentation](https://help.github.com/articles/using-pull-requests/). + +Anyone interested in type stubs may review your code. One of the +maintainers will merge your pull request when they think it's ready. +For every pull request, we aim to promptly either merge it or say why +it's not yet ready; if you go a few days without a reply, please feel +free to ping the thread by adding a new comment. + +To get your pull request merged sooner, you should explain why you are +making the change. For example, you can point to a code sample that is +processed incorrectly by a type checker. It is also helpful to add +links to online documentation or to the implementation of the code +you are changing. + +Also, do not squash your commits or use `git commit --amend` after you have submitted a pull request, as this +erases context during review. We will squash commits when the pull request is merged. +This way, your pull request will appear as a single commit in our git history, even +if it consisted of several smaller commits. + +At present the maintainers are (alphabetically): +* David Fisher (@ddfisher) +* Łukasz Langa (@ambv) +* Jukka Lehtosalo (@JukkaL) +* Ivan Levkivskyi (@ilevkivskyi) +* Matthias Kramm (@matthiaskramm) +* Greg Price (@gnprice) +* Sebastian Rittau (@srittau) +* Guido van Rossum (@gvanrossum) +* Shantanu (@hauntsaninja) +* Rune Tynan (@CraftSpider) +* Aku Viljanen (@Akuli) +* Jelle Zijlstra (@JelleZijlstra) + +NOTE: the process for preparing and submitting changes also applies to +maintainers. This ensures high quality contributions and keeps +everybody on the same page. Avoid direct pushes to the repository. + +## Third-party library removal policy + +Third-party packages are generally removed from typeshed when one of the +following criteria is met: + +* The upstream package ships a py.typed file for at least 6-12 months, or +* the package does not support any of the Python versions supported by + typeshed. + ## Maintainer guidelines Maintainers should follow these rules when processing pull requests: From 33b010f6356b772581961a45e697e39faa6727fd Mon Sep 17 00:00:00 2001 From: Sebastian Rittau Date: Wed, 12 May 2021 23:42:46 +0200 Subject: [PATCH 11/20] Move maintainers to a separate file --- MAINTAINERS.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 MAINTAINERS.md diff --git a/MAINTAINERS.md b/MAINTAINERS.md new file mode 100644 index 000000000000..dc7271510c26 --- /dev/null +++ b/MAINTAINERS.md @@ -0,0 +1,14 @@ +At present the maintainers are (alphabetically): + +* David Fisher (@ddfisher) +* Łukasz Langa (@ambv) +* Jukka Lehtosalo (@JukkaL) +* Ivan Levkivskyi (@ilevkivskyi) +* Matthias Kramm (@matthiaskramm) +* Greg Price (@gnprice) +* Sebastian Rittau (@srittau) +* Guido van Rossum (@gvanrossum) +* Shantanu (@hauntsaninja) +* Rune Tynan (@CraftSpider) +* Aku Viljanen (@Akuli) +* Jelle Zijlstra (@JelleZijlstra) From e76efa049ae7269d2ed1f77de3c31d53c07f26bd Mon Sep 17 00:00:00 2001 From: Sebastian Rittau Date: Wed, 12 May 2021 23:43:04 +0200 Subject: [PATCH 12/20] Move maintainers to a separate file --- CONTRIBUTING.md | 18 ++---------------- 1 file changed, 2 insertions(+), 16 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 46b520cc9adf..f99dad714f2c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -22,8 +22,8 @@ are important to the project's success. 4. [Submit your changes](#submitting-changes) by opening a pull request. 5. You can expect a reply within a few days: * Diffs are merged when considered ready by the core team. - * Feel free to ping the core team if your pull request goes without - a reply for more than a few days. + * Feel free to ping the [core team](MAINTAINERS.md) if your pull request + goes without a reply for more than a few days. For more details, read below. @@ -505,20 +505,6 @@ erases context during review. We will squash commits when the pull request is me This way, your pull request will appear as a single commit in our git history, even if it consisted of several smaller commits. -At present the maintainers are (alphabetically): -* David Fisher (@ddfisher) -* Łukasz Langa (@ambv) -* Jukka Lehtosalo (@JukkaL) -* Ivan Levkivskyi (@ilevkivskyi) -* Matthias Kramm (@matthiaskramm) -* Greg Price (@gnprice) -* Sebastian Rittau (@srittau) -* Guido van Rossum (@gvanrossum) -* Shantanu (@hauntsaninja) -* Rune Tynan (@CraftSpider) -* Aku Viljanen (@Akuli) -* Jelle Zijlstra (@JelleZijlstra) - NOTE: the process for preparing and submitting changes also applies to maintainers. This ensures high quality contributions and keeps everybody on the same page. Avoid direct pushes to the repository. From 300247dc609507017d1277f4d755b89a82688798 Mon Sep 17 00:00:00 2001 From: Sebastian Rittau Date: Wed, 12 May 2021 23:44:57 +0200 Subject: [PATCH 13/20] Move a paragraph to the maintainer guidelines --- CONTRIBUTING.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f99dad714f2c..219430b94fe1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -338,7 +338,7 @@ 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`). -NOTE: there are stubs in this repository that don't conform to the +*Note:* There are stubs in this repository that don't conform to the style described above. Fixing them is a great starting point for new contributors. @@ -505,10 +505,6 @@ erases context during review. We will squash commits when the pull request is me This way, your pull request will appear as a single commit in our git history, even if it consisted of several smaller commits. -NOTE: the process for preparing and submitting changes also applies to -maintainers. This ensures high quality contributions and keeps -everybody on the same page. Avoid direct pushes to the repository. - ## Third-party library removal policy Third-party packages are generally removed from typeshed when one of the @@ -520,6 +516,10 @@ following criteria is met: ## Maintainer guidelines +The process for preparing and submitting changes also applies to +maintainers. This ensures high quality contributions and keeps +everybody on the same page. Avoid direct pushes to the repository. + Maintainers should follow these rules when processing pull requests: * Always wait for tests to pass before merging PRs. @@ -529,7 +529,7 @@ Maintainers should follow these rules when processing pull requests: intermediate commit messages. * If stubs for a new library are submitted, notify the library's maintainers. -When reviewing PRs, follow these guidelines: +When reviewing pull requests, follow these guidelines: * Typing is hard. Try to be helpful and explain issues with the PR, especially to new contributors. From cc33d36bd5592a7e83a22ca1e47b94a8714b28cd Mon Sep 17 00:00:00 2001 From: Sebastian Rittau Date: Wed, 12 May 2021 23:47:52 +0200 Subject: [PATCH 14/20] link fix --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 219430b94fe1..1f1aeb9f6797 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -119,7 +119,7 @@ Python function annotations ([PEP 3107](https://www.python.org/dev/peps/pep-3107 are used to describe the signature of each function or method. See [PEP 484](http://www.python.org/dev/peps/pep-0484/) for the exact -syntax of the stub files and [CONTRIBUTING.md](CONTRIBUTING.md) for the +syntax of the stub files and [below](#stub-file-coding-style) for the coding style used in typeshed. ### What to include From b2161c61fcb20d70ded595b7daa6b91c1c9a5600 Mon Sep 17 00:00:00 2001 From: Sebastian Rittau Date: Thu, 13 May 2021 00:02:03 +0200 Subject: [PATCH 15/20] IRC -> Gitter --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 0eef079fe233..5f1545ad2d8d 100644 --- a/README.md +++ b/README.md @@ -73,7 +73,7 @@ unblocked!) ## Code of Conduct Everyone participating in the typeshed community, and in particular in -our issue tracker, pull requests, and IRC channel, is expected to treat +our issue tracker, pull requests, and Gitter channel, is expected to treat other people with respect and more generally to follow the guidelines articulated in the [Python Community Code of Conduct](https://www.python.org/psf/codeofconduct/). From d9dc26c02b438deac2760b7d5d773be40f8fdf17 Mon Sep 17 00:00:00 2001 From: Sebastian Rittau Date: Thu, 13 May 2021 00:07:08 +0200 Subject: [PATCH 16/20] Remove note about stubs not following the convention --- CONTRIBUTING.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1f1aeb9f6797..7de41444807a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -338,10 +338,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`). -*Note:* There are stubs in this repository that don't conform to the -style described above. Fixing them is a great starting point for new -contributors. - ## Running the tests The tests are automatically run on every PR and push to the repo. From 5fc8ec7a2ddcf6dc20c658983b098315055b4e17 Mon Sep 17 00:00:00 2001 From: Sebastian Rittau Date: Thu, 13 May 2021 00:31:29 +0200 Subject: [PATCH 17/20] Unify wording to 'maintainers' --- CONTRIBUTING.md | 4 ++-- README.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7de41444807a..f29c80622944 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -21,8 +21,8 @@ are important to the project's success. for all pull requests. 4. [Submit your changes](#submitting-changes) by opening a pull request. 5. You can expect a reply within a few days: - * Diffs are merged when considered ready by the core team. - * Feel free to ping the [core team](MAINTAINERS.md) if your pull request + * Diffs are merged when considered ready by a maintainer. + * Feel free to ping the [maintainers](MAINTAINERS.md) if your pull request goes without a reply for more than a few days. For more details, read below. diff --git a/README.md b/README.md index 5f1545ad2d8d..e2d204384517 100644 --- a/README.md +++ b/README.md @@ -50,7 +50,7 @@ place to start a discussion of any of the above or most any other topic concerning the project. For less formal discussion, try the typing chat room on -[gitter.im](https://gitter.im/python/typing). Some Mypy core developers +[gitter.im](https://gitter.im/python/typing). Some typeshed maintainers are almost always present; feel free to find us there and we're happy to chat. Substantive technical discussion will be directed to the issue tracker. From 49edcb588cf68bf2d0e6736b090621d5bfb48b44 Mon Sep 17 00:00:00 2001 From: Sebastian Rittau Date: Thu, 13 May 2021 00:48:18 +0200 Subject: [PATCH 18/20] Please be patient --- CONTRIBUTING.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f29c80622944..8d60018830ce 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,10 +20,8 @@ are important to the project's success. usually is not needed, because the tests run automatically on GitHub Actions for all pull requests. 4. [Submit your changes](#submitting-changes) by opening a pull request. -5. You can expect a reply within a few days: - * Diffs are merged when considered ready by a maintainer. - * Feel free to ping the [maintainers](MAINTAINERS.md) if your pull request - goes without a reply for more than a few days. +5. You can expect a reply within a few days, but please be patient when + it takes a bit longer. For more details, read below. From 3c1b175d85b396e99387acacde8bcc5bf2439ebe Mon Sep 17 00:00:00 2001 From: Sebastian Rittau Date: Thu, 13 May 2021 00:51:09 +0200 Subject: [PATCH 19/20] Remove mention of obsolete arguments --- CONTRIBUTING.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8d60018830ce..8afdfa6c4f4d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -393,8 +393,7 @@ You can restrict mypy tests to a single version by passing `-p2` or `-p3.9`: ### pytype\_test.py This test requires Python 2.7 and Python 3.6. Pytype will -find these automatically if they're in `PATH`, but otherwise you must point to -them with the `--python27-exe` and `--python36-exe` arguments, respectively. +find these automatically if they're in `PATH`. Run using: ``` (.venv3)$ python3 tests/pytype_test.py From a202df20ad2eaf6fe2ba0de544231d0fcc5a0910 Mon Sep 17 00:00:00 2001 From: Sebastian Rittau Date: Thu, 13 May 2021 00:53:29 +0200 Subject: [PATCH 20/20] Remove issue tracker conventions section --- README.md | 15 --------------- 1 file changed, 15 deletions(-) diff --git a/README.md b/README.md index e2d204384517..8d90b31dc48a 100644 --- a/README.md +++ b/README.md @@ -55,21 +55,6 @@ are almost always present; feel free to find us there and we're happy to chat. Substantive technical discussion will be directed to the issue tracker. -## Issue-tracker conventions - -We aim to reply to all new issues promptly. We'll assign one or more -labels to indicate we've triaged an issue, but most typeshed issues -are relatively simple (stubs for a given module or package are -missing, incomplete or incorrect) and we won't add noise to the -tracker by labeling all of them. Please see the -[list of all labels](https://github.com/python/typeshed/issues/labels) -for a detailed description of the labels we use. - -Sometimes a PR can't make progress until some external issue is -addressed. We indicate this by editing the subject to add a ``[WIP]`` -prefix. (This should be removed before committing the issue once -unblocked!) - ## Code of Conduct Everyone participating in the typeshed community, and in particular in