Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 2 commits into from
Jan 12, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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
49 changes: 49 additions & 0 deletions docs/spec/meta.rst
Original file line number Diff line number Diff line change
@@ -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.
Loading