PEP 676: PEP Infrastructure Process

You could also ask for a PEP Delegate. I’d expect the SC to approve that quickly and then you’d be unblocked from their backlog.

2 Likes

Would you be willing to act as delegate Barry?

I didn’t realise there was any sort of backlog, so if I don’t find someone to act as a delegate then I’ll submit fairly quickly.

A

1 Like

Yes. I should have just come right out and offered. :smile:

4 Likes

Just checking, to make sure the PEP is as strong as it can be—does it capture the additional improvements that have or will be implemented that came up as part of this process, e.g. toggleable dark theme, better inter-PEP/etc. links, improved navigation, fully documented and easily maintainable & extensible without tons of hacks, allowing appendices/supplementary material to be included in subdirs, etc? Collectively, this helps make clear that it is more of a leap forward over the old system with concrete benefits for PEP editors and maintainers alike, rather than just churn to switch to the latest hotness (the most likely objection I could envision). Or @barry do you think its plenty strong as-is, since you’re already aware of most of these provements?

1 Like

I think it might be useful to capture the documentation & dark mode in the PEP, but I wouldn’t go into much detail.

I’ll write something up after dinner.

A

1 Like

Barring slight confusion over what the request to the Council is for [1], the notification to the Council of Barry’s nomination as PEP Delegate has been submitted as PEP-Delegate notification for PEP 676 · Issue #97 · python/steering-council · GitHub

A


  1. see PEP 1: Further refine phrasing and organization of PEP-Delegate description by CAM-Gerlach · Pull Request #2257 · python/peps · GitHub ↩︎

2 Likes

PEP 676 has now been updated to mention the documentation & colour schemes, thanks to Cam for the prompt!

A

3 Likes

… and the council approved Barry as the delegate.

4 Likes

What is the status on PEP 676 now? Is there anything blocking us from making a decision? It would be helpful for PEP editing work to come to a decision soon so we don’t have to maintain two rendering systems.

1 Like

As far as I’m aware there are no blockers, just waiting on a pronouncement.

A

Thanks! Then consider this a gentle poke for @barry to see if there’s anything blocking a pronouncement :smile:

1 Like

Yay! I was waiting for a poke. I’ll review the PEP and get back to you.

5 Likes

BTW @barry , not sure if you got the chance to notice, but in response to feedback (including yours) @AA-Turner has implemented a number of further useful enhancements using new rendering system since the PEP was last updated, including PEP numbers, names and even section names in the pop-up titletext for linked PEPs (I think that one was your suggestion), with the same for footnotes soon to follow; more useful and friendlier handling for Discussions-To links (also indirectly based on your feedback on the PEP 1 issue), and now automatic link parsing for Post-History with a greatly simplified and more familiar syntax relative to reST links, as well as other helpful tweaks.

@AA-Turner , if PEP 676 were accepted tomorrow, do you have a rough ETA on how long it would be until the rendering system it specifies was deployed in production and the canonical location for viewing PEPs? Just trying to get a sense for how much longer we would have to live with the limitations of the old one, and when we can start relying on the new features (e.g. :ref:, the new Post-History, etc).

The PEP looks great to me, thank you for the great work!

I’m almost ready to pronounce, but I have a couple of questions first, and a suggestion for possible future enhancement (non-blocking).

  • Have you checked with the python.org infrastructure team to verify that the redirects and existing python.org/dev/peps changes are acceptable?
  • How long would it take to roll out all the infra changes?
  • If there is some delay in doing the redirects and updating python.org, does it make sense to stand up peps.python.org now?
  • What is your plan for communicating the changes to the wider Python community?
  • Have you posted the PEP to python-dev@python.org (and maybe the Documentation WG, although I don’t know the status of that WG, but I’m sure @willingc does).

Non-blocking suggestion for the future: I’d like to have direct access to the breadcrumbs at the top of the PEP, even when I scroll through to read it. Perhaps keep the header from scrolling, or move the breadcrumbs to the left contents area.

1 Like

Very kind, thank you!

No. Who would be the best contact here? There is discussion of this earlier in this thread, see:

Good point – we’d need a contact to set up the domain name at least, perhaps the same guy as we get in touch with from the website team.

I haven’t given much thought to this, partly as the auto-redirects will make the canonical source reasonably obvious, and “old” links will continue to work.

I’d be happy for advice here as to what more would be needed.

Yes, see Mailman 3 PEP 676 -- PEP Infrastructure Process - Python-Dev - python.org

There was conversation about that previously, and Use Sphinx for pep builds and better rendering · Issue #10 · python/docs-community · GitHub, but there has been no input from the documentation working group as a formal entity into this proposal.

Sounds good.

A

I believe infrastructure@ is still the best contact, but if @EWDurbin is on board, that’s good enough for me.

I’d suggestion crafting a short announcement and posting to python-list@ and python-announce@.

1 Like

Now that final PEP resolution appears imminent, this is definitely the biggest open question for me that I’m looking for at least a ballpark estimate on for planning purposes, and has significant implications both for my/our onging and future linting, infra and PEP 1/12 PRs, as well as my own work to complete PEP 639.

Along with @AA-Turner himself, we’re both members of the Docs Team that supports the WG, attend the meetings and are active on the Discord, and IIRC I brought it up at the WG meeting, and no one raised any concerns.

In terms of formal assent/voting, per the group’s draft charter, it doesn’t appear that the PEP process is explicitly in scope, since the Docs WG serves as the editorial board for the docs, while the PEP Editors fulfill a similar role for the PEPs. Also, the general the overall direction amongst SC members, PEP editors and specialized communities seems to be toward moving the PEPs further away from being living documentation and more specifically focusing on being change proposals (though this strategic goal hasn’t been officially formalized yet).

This proposal should be fairly transparent to the wider Python community; the main changes they will see are (are there any I’m missing?):

  • The theme used for the PEPs will change somewhat, with a new dark mode and many other improvements, but this is mostly aesthetic with some functional enhancements.
  • The canonical URL will change, but redirects will remain in place indefinitely

For PEP authors, essentially all the previous syntax and formatting they are used to continue to work as before, with the changes being:

  • The command used to build the PEPs will change, and the requirements.txt updated accordingly
  • They will be able to use extended Sphinx roles and directives, if they choose, and best practices have evolved accordingly

Between @AA-Turner and myself, we’ve already taken care of the additions to the README, Contributing Guide, PEP 1 and PEP 12 to reflect this without dropping compat with the legacy build script, and I will continue to work further on this as we carry out the transition.

The next Docs WG meeting is planned for Monday. I’ve added a note to the agenda. But IMO it shouldn’t block anything.

1 Like

Okay cool. Ee is pinged on this thread, and I suggest reaching out to infrastructure@ now to coordinate. My only mild concern was if something in the Specification section needed to change, but we’ll just treat that as we would implementation for a Standards Track PEP (i.e. it doesn’t necessarily need to be complete before the PEP is approved).

:+1:

That was always my position when we designed the PEP process originally, so I’m +1 on formalizing that.

Sure, but from a user perspective, I think it’s worth celebrating all this great work, so I would still recommend sending announcements as per above.

Agreed.

1 Like