Spec: Add "meta" file describing process for changing the spec (#1573)

JelleZijlstra · web-flow · commit 46d7064d21f3 · 2024-01-11T17:09:55.000-08:00
I think this isn't currently very clearly documented. Hopefully this
will be a good place to find it.
diff --git 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
@@ -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
@@ -0,0 +1,49 @@
+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 <https://github.com/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 <https://peps.python.org/topic/typing/>`__.
+
+Changes that need Typing Council approval go through three steps:
+
+- Open a discussion on `discuss.python.org <https://discuss.python.org/c/typing/32>`__
+  describing the issue.
+- Open a PR on `python/typing <https://github.com/python/typing>`__
+  that changes the spec and, if applicable, the
+  `conformance test suite <https://github.com/python/typing/tree/main/conformance>`__.
+- `Open an issue <https://github.com/python/typing-council/issues/new>`__ on
+  the Typing Council's issue tracker asking for a decision.
+
+The Typing Council has `published <https://github.com/python/typing-council/blob/main/README.md>`__
+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.
