PEP 729: Typing governance process

PEPs
1

PEP 729 proposes the creation of a Typing Council that would help shepherd the Python type system by creating a conformance test suite and specification. We previously discussed an earlier stage of this idea in Proposed new typing governance process - #34 by Jelle.

20 Likes
2

Thanks again for the @Jelle and @hauntsaninja! A few remarks:

  • For the “Mandate” section: I’d be interested in how far the Typing Council should be proponents of the type system. For example, if there is significant resistance from the general Python community about a typing-related PEP, should the TC advocate the usefulness of the PEP to the SC, should it try to present a balanced view, or should it weigh in on the technical side from a typing perspectivy only?
  • I find the sentence “There is an expectation that at least one person will voluntarily resign from the Typing Council each year.” a bit problematic. I think cycling through members from time to time is important, but this could lead to one or two “firmly entrenched” members, while putting pressure on the third member to resign. Maybe it would make more sense to have something like “There is an expectation that each member serves at most three consecutive years before resigning.”
  • Another documentation project that I’d like to see tackled are tutorials and howtos. Especially a general “typing tutorial”, but also more specialized howtos like “How to add typing to an existing code base” or “How to type a library”.
9 Likes
3

This PEP gets a big +1 from me! As a type checker maintainer, I would find it very useful for typing to have a clearer decision-making structure, especially for clarifying intended behavior in currently underspecified cases.

I like Sebastian’s idea of soft term limits; that seems like a good way of getting fresh perspectives and ideas into the council regularly.

7 Likes
4

I’m also +1 on this proposal. Just to echo what @rchen152 said, having a clearer decision-making structure would be really beneficial to me as a type checker maintainer. A more formal specification and conformance test suite would also be very welcome. This will translate to a better experience for users of the Python type system and related tooling.

Thanks @Jelle & @hauntsaninja for your leadership and all the thought and hard work that went into this proposal.

3 Likes
5

Thanks for the feedback! Some replies to Sebastian:

I think TC members should think about the language as a whole when providing a recommendation on a PEP. Naturally though, the people who serve on the TC may be more inclined to think that what’s good for typing is what’s good for the language. The Steering Council will still make any decisions on adding new syntax or otherwise adapting the rest of the language towards typing.

That’s a good point and I like your proposed wording.

However, I’m thinking of expanding the size of the Council from 3 to 5 to provide more representation. If so, it likely also makes sense to increase the soft term limit to 5 years.

I agree this is important, but I would like to temper expectations. The problems the Typing Council solves are primarily about decision-making authority: the Council will have the authority to coordinate and approve changes in the type system. But to get such tutorials, we don’t need authority, we simply need people with the time and inclination to write the material. I would encourage anyone who is interested to contribute documentation to GitHub - python/typing: Python static typing home. Hosts the documentation and a user help forum. so we can publish it at Static Typing with Python — typing documentation.

2 Likes
6

Thanks @Jelle and @hauntsaninja for taking the time to put this PEP together. I’m overall quite pleased with it. :+1:

Minor clarifications requested

The council would operate primarily through reviews of GitHub PRs.

To clarify, is this talking about PRs to the to-be-created typing spec and conformance suite? To python/typing specifically? Or to somewhere else?

Members of the council will be eligible to sponsor PEPs. If this PEP is accepted, PEP 1 should be amended to note this fact.

Is this saying that members of the Typing Council should not be excluded from sponsoring PEPs? Is it saying that those wishing to propose a typing-related PEP are recommended to go to the council first to find a sponsor? Or something else?

Responses to other comments

+1 for a soft term limit

7

The PEP doesn’t currently specify what repos should be used or created for the Council’s various responsibilities. I think the exact organization can be left up to the initial Council, but here are some possible (partially mutually exclusive) approaches:

It’s saying that members of the Council are automatically eligible to sponsor PEPs. Currently, only core devs and PEP editors have that privilege. The Council is expected to include members who are not core devs.

1 Like
8

I’m just posted a change to the PEP to list the proposed initial composition of the Council. At Guido’s suggestion, we’ll expand to five people, but with a possibility to make the Council smaller in the future at its own discretion.

The proposed initial members are:

  • @erictraut (author of pyright and of PEPs 647, 681, 695)
  • @guido (author of PEPs 484 and 526, among other work)
  • @rchen152 (maintainer of pytype)
  • @hauntsaninja (core dev; maintainer of mypy and typeshed)
  • myself (core dev; maintainer of typeshed, mypy, typing-extensions, and pyanalyze; author of PEPs 688 and 702)

With this, we’re getting close to having the PEP ready for submission to the Steering Council.

15 Likes
9

I just submitted the PEP to the SC.

In the meantime, I’d like to discuss how the Council’s various responsibilities should be organized in terms of GitHub repos. This is intentionally not precisely specified in the PEP so that the Council retains flexibility, but it’s good to think about it anyway. I’ll write out my thoughts and conclude with a proposal, but I’m happy to hear other opinions.

  • The user-facing reference should live at Type System Reference — typing documentation and the python/typing repo—there’s already something there, and it’s a good place.
  • The spec and conformance test suite should be in the same repo, so that it’s easy to review a proposed spec change and its corresponding test suite changes together.
  • The spec should be hosted at typing.readthedocs.io, so as much as possible of the typing-related documentation is under one domain.
  • There should be a dedicated repo for asking the Council to make a decision (analogous to python/steering-council). This allows people who want to follow along without too much noise to follow just this repo. It also creates a clear record of the Council’s decisions.

So with that in mind, I propose that the Council should work with two repos:

  • python/typing contains the user-facing reference, spec, and conformance test suite. The former two power a docs site at typing.readthedocs.io (though come to think of it, maybe we should move it to typing.python.org?).
  • python/typing-council doesn’t contain any significant code or docs, but issues can be opened there to request the Council to make a decision. The repo could contain practical information about the Council, such as current membership and procedures.

As a corollary, spec/conformance test suite changes come in three kinds:

  • Changes that don’t affect content (wording improvements, reorganization, test cases for features that aren’t covered yet) are handled through PRs to python/typing that may be merged by anyone with access to that repo. The Council should supervise such changes and speak up if anything needs more discussion.
  • Content changes that are relatively small are handled by the Council. (For example, Inconsistencies between `Type` and `type` should take this path.) After initial discussion, someone creates a PR to the spec and test suite. Then they open an issue on the python/typing-council repo asking for a decision, and also bring up the issue here on Discuss. After at least a week, the Council makes a decision.
  • Larger changes, such as new type system features, need a PEP. Such PEPs would come with proposed changes to the spec and test suite. When the PEP is ready for a decision, the author posts on the python/typing-council and python/steering-council repos. The Typing Council then comes up with a recommendation, and the Steering Council makes the final decision.

The exact boundaries between these levels would be up to the Council.

How should the Council make decisions? The PEP suggests decision-making should mostly take place on GitHub. Possibly this will be impractical if the Council finds it important to speak with one voice. However, one approach is simply that the Council members discuss their decision on the issue in the typing-council repo.

7 Likes
10

Personal hat: Overall I like this PEP and the Typing Council definition. Good use of past examples.

Some minor phrasing nits in 729 today: (none of these block me from recommending to the rest of the SC that we should accept it, but if you have better phrasing, feel free to make edits)

Under “Specification for the type system” section:

" For projects such as typeshed, or libraries that want to be compatible with multiple type checkers, it provides a set of rules that they can follow"* …

and later:

“the specification is not aimed at end users of typing, who typically do not need to worry about compatibility across type checkers.” …

This latter didn’t read as really true to me because I consider any library maintainer to be an “end user of typing” which puts them in the first sentence camp. I suspect you meant something different by “end user of typing” than I read it as. I consider anyone who uses any form of static or runtime type checking based on annotations to be an end user of typing. Thus annotated library maintainers are also end users of typing.

I think your higher level point is valid though. The technical spec might not be something everyone can easily understand. A user-facing reference will be written for that purpose.

At the end of “Operations and process” it states “Members of the council will be eligible to sponsor PEPs. If this PEP is accepted, PEP 1 should be amended to note this fact.”

I don’t know if that will matter or not. There’s enough core devs involved in typing that I suspect there may already be enough already pep-sponsor-enabled people in the community? Regardless, I have no problem with the concept. It makes sense to me given one thing the Typing Council may be doing is deciding which PEPs need to be sent up to the SC. (If it were ever to become an issue regardless of who is involved the SC could chime in)

Otherwise as far as PEPs go, it feels like there is a little conflation of concepts in here with the typing council setup described along with what seem to me like detailed specifications of projects you may take on - when in reality I think how those projects are accomplished is ultimately intended to be up to the new Typing Council to decide. So the list of goals is great, but once established I assume those to be “implementation details” that y’all and the typing community would work out - if you change your mind on “how”, that’s sort of the point of the TC. But it’s a great seed list of "what"s.

The PEP could probably have been shorter with that in mind, but I wouldn’t go removing any of it. It is nice to see your initial goals already being thought out.

3 Likes
11

Thanks, that’s great to hear!

Good point. What I was trying to say that application developers usually won’t need to worry about the spec, only about satisfying their chosen type checker. I’ll submit a PR to reword that.

I felt it was important to put all Council members on a level playing field in terms of being able to advocate a proposal. Also, selfishly, I’ve ended up sponsoring a lot of typing-related PEPs in the last few years and it can be a fair amount of work, so I don’t mind expanding the pool of people who are able to act as sponsors :slight_smile:

That’s a reasonable point. On the other hand, I feel the PEP is a good place to get community consensus on some of these aspects. Also, it’s hard to make a good case for why the Council is useful without a bit of detail on what it will be doing.

3 Likes
12

The SC has accepted this PEP. :slightly_smiling_face:

13 Likes
13

Big congrats to everyone involved, and especially to the new council and the PEP authors @Jelle and @hauntsaninja ! Exciting times ahead.

7 Likes