diff --git a/README.md b/README.md index eb7472be0..09fb4f1b0 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,10 @@ For conversations that are more suitable to a chat platform, you can use one of This GitHub repository is used for several things: - The documentation at [typing.readthedocs.io](https://typing.readthedocs.io/) - is maintained in the [docs directory](./docs). + is maintained in the [docs directory](./docs). This includes the + [specification](https://typing.readthedocs.io/en/latest/spec/index.html) for the + type system. See especially [the update procedure](https://typing.readthedocs.io/en/latest/spec/meta.html) + for the spec. - A [discussion forum](https://github.com/python/typing/discussions) for typing-related user help is hosted here. diff --git a/docs/spec/index.rst b/docs/spec/index.rst index 028e0fcbb..dbee50c10 100644 --- a/docs/spec/index.rst +++ b/docs/spec/index.rst @@ -6,6 +6,7 @@ Specification for the Python type system :caption: Contents: type-system + meta concepts annotations special-types diff --git a/docs/spec/meta.rst b/docs/spec/meta.rst new file mode 100644 index 000000000..b80c581c6 --- /dev/null +++ b/docs/spec/meta.rst @@ -0,0 +1,48 @@ +Meta-topics +=========== + +About this specification +------------------------ + +This document was created following the acceptance of :pep:`729` +to serve as a specification for the Python type system. The +initial text consists of the "Specification" sections of :pep:`484` +and subsequent typing-related PEPs, pasted together and reorganized. +This creates a document that encompasses all aspects of the type +system that have been specified in PEPs, but not necessarily a +coherent whole. The hope is that incremental improvements will +be made to this document to make it more coherent and complete. + +Changing the specification +-------------------------- + +Changes to the specification come in three kinds: + +- Minor, non-substantive changes can simply be proposed as PRs to + the `python/typing `__ repository, + and may be merged by anyone with commit access. Such changes may + include formatting fixes, linking improvements, etc. +- Major changes should go through the PEP process, as described in + :pep:`1`. What counts as a major change is not precisely defined, + but it would generally include any change of a similar magnitude + to `previous typing PEPs `__. +- Substantive changes that do not rise to the level of a PEP must + be approved by the Typing Council. The procedure is described below. + +Changes that need Typing Council approval go through three steps: + +- Open a discussion on `discuss.python.org `__ + describing the issue. +- Open a PR on `python/typing `__ + that changes the spec and the `conformance test suite `__. +- `Open an issue `__ on + the Typing Council's issue tracker asking for a decision. + +The Typing Council has `published `__ +some guidance on useful information to gather when proposing a change +to the spec, including: + +- A survey of the current behavior of major type checkers. +- A rationale for why the proposed behavior is better than alternatives. +- An implementation or proposed implementation of the proposed behavior + in at least one major type checker.