From fa459b1c4b98b916254eb73505ac91cf482358e7 Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Wed, 10 Jan 2024 20:22:32 -0800 Subject: [PATCH 1/2] Spec: Add "meta" file describing process for changing the spec I think this isn't currently very clearly documented. Hopefully this will be a good place to find it. --- README.md | 5 ++++- docs/spec/index.rst | 1 + docs/spec/meta.rst | 48 +++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 53 insertions(+), 1 deletion(-) create mode 100644 docs/spec/meta.rst diff --git a/README.md b/README.md index eb7472be..09fb4f1b 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 028e0fcb..dbee50c1 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 00000000..b80c581c --- /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. From 7612ca4490973566a6bacab1fa25f9337fd40a0e Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Thu, 11 Jan 2024 08:08:24 -0800 Subject: [PATCH 2/2] Reorder, don't always need conformance test changes --- docs/spec/meta.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/spec/meta.rst b/docs/spec/meta.rst index b80c581c..46f23217 100644 --- a/docs/spec/meta.rst +++ b/docs/spec/meta.rst @@ -22,19 +22,20 @@ Changes to the specification come in three kinds: the `python/typing `__ repository, and may be merged by anyone with commit access. Such changes may include formatting fixes, linking improvements, etc. +- Substantive changes that do not rise to the level of a PEP must + be approved by the Typing Council. The procedure is described below. - 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 `__. + that changes the spec and, if applicable, the + `conformance test suite `__. - `Open an issue `__ on the Typing Council's issue tracker asking for a decision.