Skip to content

Commit

Permalink
Spec: Add "meta" file describing process for changing the spec
Browse files Browse the repository at this point in the history
I think this isn't currently very clearly documented. Hopefully this
will be a good place to find it.
  • Loading branch information
JelleZijlstra committed Jan 11, 2024
1 parent 7b192dc commit fa459b1
Show file tree
Hide file tree
Showing 3 changed files with 53 additions and 1 deletion.
5 changes: 4 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
1 change: 1 addition & 0 deletions docs/spec/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ Specification for the Python type system
:caption: Contents:

type-system
meta
concepts
annotations
special-types
Expand Down
48 changes: 48 additions & 0 deletions docs/spec/meta.rst
Original file line number Diff line number Diff line change
@@ -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 <https://github.com/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 <https://peps.python.org/topic/typing/>`__.
- 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 <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 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.

0 comments on commit fa459b1

Please sign in to comment.